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Preface 


This manual is one of a series designed to instruct and guide the programmer in the use 
of the SPERRY UNIVAC Operating System/3 (OS/3). This manual specifically describes 
OS/3 basic data management and its effective use. Its intended audience is the 
applications programmer with a basic knowledge of data processing, but with limited 
programming experience, as well as the seasoned applications programmer. 


Two other manuals are available that cover OS/3 basic data management; one is an 
introductory manual and the other is a programmer reference manual (PRM). The 
introductory manual briefly describes OS/3 basic data management and its facilities. The 
PRM provides the characteristics of OS/3 basic data management in skeletal form and is 
intended as a quick-reference document for the programmer experienced in the use of 
OS/3 basic data management. 


For systems with interactive facilities, an additional series of manuals is provided to 
instruct and guide the programmer in the use of OS/3 consolidated data management. 
These are: x 
= Introduction to consolidated data management, UP-8824 


= Consolidated data management concepts and facilities, UP-8825 


a Consolidated data management macro language user guide/programmer reference, 
UP-8826 


In general, any further references to the term data management in this user guide imply 
basic data management. 


This user guide is divided into the following parts: 

# PART 1. OS/3 DATA MANAGEMENT 
Introduces OS/3 data management in terms of what it is and how it is used; 
introduces and briefly describes consolidated data management; describes the data 


management/user interface and the relation of data management to other OS/3 
software. 
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PART 2. CARD, DISKETTE, and PRINTER FILES 


Describes file and format conventions and the function and operation of OS/3 data 
management in relation to punched card, diskette, and printer files. 


PART 3. MAGNETIC TAPE FILES 


Describes file and format conventions and the function and operation of OS/3 data 
management in relation to magnetic tape files. 


PART 4. DISK FILES 


Describes file and format conventions and function and operation of OS/3 data 
management as related to disk files. Describes the indexed sequential access method 
(ISAM) both with and without an index structure, the sequential access method 
(SAM), the direct access method (DAM), the indexed random access method (IRAM), 
the multiple indexed random access method (MIRAM), and the nonindexed access 
method. Also includes information on disk space management. 


PART 5. PAPER TAPE FILES 


Describes record, character, and file conventions and the functions of OS/3 data 
management for perforated paper tape files. 


PART 6. APPENDIXES 


Provide selected functional characteristics of peripheral devices relevant to data 
management use; explain the OS/3 data management procedures for. error and 
exception handling; compare the EBCDIC/ASCII/Hollerith codes and other card codes 
used in OS/3; describe the systems standard labels for magnetic tape and disk files; 
and describe the consolidated data management migration considerations. 


Statement Conventions 


The conventions used to delineate the data management macroinstructions are: 


Positional parameters must be written in the order specified in the operand field and 
must be separated by commas. When a positional parameter is omitted, the comma 
must be retained to indicate the omission, except for the case of omitted trailing 
parameters. . 


Examples: 


Assume that CNTRL is a data management macroinstruction with three optional 
positional parameters: A, B, and C. 


TAG1 CNTRL A 
TAG2 CNTRL A,B 
TAG3 CNTRL A,B,C 
TAG4 CNTRL A,,C 


UP-8068 Rev. 4°. SPERRY UNIVAC 0S/3 Preface 3. - 
BASIC DATA MANAGEMENT - 


=. A keyword parameter consists of a word or a code immediately followed by an equal 
" -- ign,. which is, in. turn, followed by a-specification..Keyword parameters can be 
“.;written' in: any order in the operand field. Commas are: required only to separate 
parameters; however, a comma must neither be coded in column 16 ofa a continuation 

line nor follow the last keyword of a string. 


Example: 


Assume that the data management DTF macro for a card file (called CARDIN) has 
three keyword parameters: [OAREA1, BLKSIZE, and WORKA. 


eon DTFCD one —AREAI. ,BLKSIZE=80, WORKA=YES 


1. Capital letters, commas, equal signs, and paranthieece must be coded exactly as 

‘. ‘shown. The exceptions. are those acronyms that are part of generic terms 
‘representing information to be supplied by the user and the commas preceding 
-.keyboard: parameters of declarative macroinstructions. (These commas serve to 
-remind.the user that keyboard parameters coded in a string must be scpaiated by 
commas.) 


Examples: 


FIELDS=([ADDR]LA2TD][,FREQ)) 
REOC=(MERGE, label, reel,to) 
CMceNUMBCHAR=n 

X‘aa'(NOV) 7 


mu Lowercase letters and words are generic terms representing ‘iGrmatin that must be 
. supplied by the user. Such lowercase terms may contain hyphens and acronyms (for 
readability). 


Examples: 
name 
start-addr 
number-of-bytes 
param-1 
CCB-name 


& Information contained within braces psaailes mandatory entries eu which one must 
be chosen. "3 


Examples: 


eae 
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2 Information contained within brackets represents optional entries that (depending 
_ .-upon. program requirements) are included or omitted. Braces within brackets signify 
- .that one of the eis entries must be Chosen if that Perenielelal is.to pe. nelged: 


Exernolas: 


[INPUT=NO] 
[OUTPUT=NO] 


Lon 


= An optional parameter which ‘has a list of optional entries may have a default 

specification which is supplied by the operating system when the parameter is not 

_ specified by the ‘user. Although the default may be specified by the: user;with no 

adverse effect, it is considered inefficient to do so. For each reference, when a default 

specification occurs in:the format delineation it is printed on a shaded background. If, 

_by parameter omission, the. operating system performs some complex. processing 

-other than parameter insertion, it is explained under. an. .if-omitted heading in the 
parameter description. pags 


Examples: 


aa i 
gem 


. An ellipse series of thes petiods) dndieates ihe omission at a sonable: number of 
entries. ph 








Example: 
param-1,...,.param-n 


= = =Commas are required when positional parameters are omitted, except stiel the last 
parameter specified. 


Example: 


positional parameter 1, positional parameter 2,, positional parameter 4 
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BASIC DATA MANAGEMENT 


1. Introduction 


1.1, THE FUNCTION OF DATA MANAGEMENT 


As you know, data processing programs produce desired results by accepting data as 
input, processing the data as appropriate, and outputting the results of the processing 
performed. 


Because most data movement and retrieval operations are inherently the same, regardless 
of the application involved, generalized, preprogrammed data manzdemmolt packages have 
been developed to assist you in performing these tasks. — 


The degree of assistance you receive fori these packages depends on the insight into 
your problems by data management developers and the success they achieve in providing 
you with the most flexible and convenient data management aids possible. The extent to 
which you can inform the data management system of the characteristics of your data and 
the specific function you want performed on that data is also integral. Therefore, it is 
necessary to establish conventions to communicate, or interface, with your data 
management system. | : | 


Data management services available to you, the programmer, via OS/3 are varied, flexible, 
and powerful. Descriptions of these services and conventions for using them go well 
beyond the scope of what a language manual can and should contain. Hence, this and 
other manuals dealing exclusively with this subject are provided to facilitate your use of 
OS/3 data management. 


1.2. BASIC AND CONSOLIDATED DATA MANAGEMENT 


Until recently, the only method of data management available under OS/3 was DTF 
(define-the-file) or basic data management. The programmers’ means for interfacing with 


_ this data management system is through certain declarative and imperative macros related 


directly to the device from which data is being retrieved or to which data is being moved. 


Now under OS/3, another method of data management is available: OD! (common data 
interface) or consolidated data management. 
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Consolidated data management generally provides all the services basic data management 
does, and then some. The single major difference is that MIRAM (multiple indexed random 
access method) files are the only disk files supported by consolidated data management. 


Consolidated data management can best be described by answering the following 
question: What does consolidated data management provide that basic data management 
doesn’t? The answers are: 


A single uniform set of declarative and imperative macroinstructions 


With basic data management, you must use a specific declarative macroinstruction 
(DTF) to define your file and the method used to access that file: DTFMT for a 
magnetic tape file, DTFPR for a printer file, DTFIS for an ISAM disk file, and so on. 
Also, with basic data management, the, imperative macroinstructions are not the 
same for all types of access methods. Different instructions are used to perform the 
same functions. For example, to write.a record to a tape file you must use a PUT 
instruction. To write a record to an ISAM file; you must use a WRITE, NEWKEY 
instruction. 


Consolidated data management, .on the other hand, has a uniform set of declarative 


_and imperative macroinstructions that you use to define and process all types of files. 


There are two declarative macroinstructions. These are the CDIB and RIB instructions. 
The CDIB instruction identifies the file and the RIB instruction describes the file 
characteristics and processing requirements. The consolidated data management 
imperative macroinstructions are also the same for all types of files. For example, if 
you want to write a record, you use the DMOUT instruction regardless of the file type. 


Canitrel structures cannot be modified 


The control structures for eaeh basic data management DTF macroinstruetion are 
generated and maintained within your program region. As a result, these structures 
can be eavenenaly meditied: and COMBLOnNse the integrity ot the file. 


Génecliddied data mapagenmelt eliminates this Babiana bacauee all control structures 
it uses are generated and maintained outside of your program region..As a result, you 
cannot inadvertently modify these control structures. This preserves the integrity of 
the file and prevents the distortion of any action taken on that file by data 
management. The CDIB and RIB macroinstructions generate parameter passing 
structures that are used to communicate information to data management. 


A single file access method for all disk files 


Basic. data management supports a variety of disk access methods: SAM, DAM, ISAM, 
ASAM, and so,on. Thus, you are faced with a decision each time you want to use a 
disk file. You must decide how you want to process the file and then select the access 
method that meets your needs or is: required my the pledterming language you 
intend to use. 


Consolidated data management uses one single disk access method, MIRAM, which 
provides all the functions provided by the various basic data management disk access 
methods. As a result, you only have to decide how you want to process the file. 
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# Enhanced file sharing 





With basic data management a file can be shared; that is, it can be used by more 
than one program at a time. This sharing, however, is limited because several 
programs can read from the file at the same time, but only one program can write to 
the file. 


Consolidated data management, however, allows complete flexibility; more than one 
program can read from or write to the file at the same time. 


# Interactive capabilities 
Basic data management does not Support interactive capabilities. 


Consolidated data management, however, supports a wide range of interactive 
capabilities. These allow you to: enter or display data from a workstation; create 
workstation screen formats that aid you in entering data or presenting output data; 
and develop and include dialogs (question and answer sessions) in your program. In 
addition, consolidated data management also supports interactive services that allow 
you to operate your jobs from a workstation, perform housekeeping tasks, and 
communicate with other workstations in your system. 


# A high degree of device independence 
Device independence means that, at program execution time, you can change the 


type of device used for a file in your program by changing the job control device 
assignment set for that file. 





This is not possible with basic data management because changing the device type 
requires changing the file definition, recompiling and relinking your program, and 
changing the job control stream before you can execute it with a different device. 


With consolidated data management, a high degree of device independence is 
possible whenever you are processing records sequentially. This is possible because 
device assignment takes place when the file is opened based upon the job control 
device assignments. As a result, you can change the device that a file is processed on 
by changing the job control device assignment set for that file. The file you have 
defined must be compatible with the types of devices you want to use. For example, if 
you define a file that has an 80-byte record size, the records can be output to a card 
punch, printer, tape, disk, diskette, or workstation. If, on the other hand, you define a 
file that has a 200-byte record size, the records can be output to a tape, disk, diskette, 
or workstation. However, they cannot be output to a card punch or printer without 
truncating the data because of the physical limitations of these devices. In addition to 
your files being compatible, your program must also be compatible with the devices 
you want to use. This means you cannot have any instructions in your program that 
are device dependent such as random operations when using a disk or diskette, forms 
control operations when using a printer, or screen management operations when 
using a workstation. 








Pes 
% 


_ 
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Use of a particular data management mode is specified at systems generation time. The 
capabilities just described are provided when consolidated data management (CDI mode) 
alone or in combination with basic data management (CDI/DTF mixed mode) is specified. 


This manual specifically describes basic data management. For more detailed information 
on consolidated data management, see the consolidated data management concepts and 
facilities, UP-8825 (current version) and the consolidated data management macro 
language user guide/programmer reference, UP-8826 (current version). 


If you want to migrate to consolidated data management, see Appendix F. This appendix 
describes the migration requirements for programs written in BAL, RPG Il, 1968 American 
National Standard COBOL, 1974 American National Standard COBOL, and FORTRAN. 
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1.3. DATA STRUCTURE 


The structural entities recognized by OS/3 data management are illustrated in the 
following diagram: 





VOLUME 
FILE 
BLOCK 
RECORD 
FIELD 
BYTE 







The hierarchy shown is not always followed exactly. The volume concept is not truly 
applicable to printers or card devices. On disk, diskettes, and magnetic tape, a file may 
sometimes be larger than a volume. A record may sometimes be equal to a block, or a 
field equal to a byte. Figure 1—1 illustrates the organization of data on typical peripheral 
devices. 


A FILE COMPRISES ONE OR MORE SPANS 
OF TRACKS ON ALL SURFACES OF PACK 


ee oe. 
TS 
aS YA 


NOTE: 


The set of tracks at a specific 
radius on all recording surfaces 
is called a cylinder. 


DISC PACK 


Figure 1—1. Organization of Data on Typical Peripheral Devices (Part 1 of 2) 
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Figure 1—1. Organization of Data on Typical Peripheral Devices (Part 2 of 2) 
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1.3.1. Definition of Terms 


The following is a brief list of terms and definitions to assist you in understanding the 
general description of data management in this section: 


block 
The portion of a file transferred into or out of main storage by a single access. 


buffer 
An area in main storage for handling a block of data. Must not be smaller than 
the blocks to be handled. 


direct addressing . 
Retrieving a specific block or record from disk storage by a single access, using 
numeric values given in a field. 


extent 
A set of contiguous tracks on disk assigned exclusively to one file. Several 
extents may be required to provide space enough for a file. 


field ‘ 
One or more contiguous characters, normally comprising a single unit of 
information. 

file 
A delimited storage space having an identifying file name; useful for subdividing 
the entire data mass into manageable groups. Also, the data residing in such a 
storage space. 

partition 
A file subdivision, which is required to have uniform block specifications. OS/3 
data management provides partition-relative block addressing, and individual 
partition extension capabilities. 

pointer } 
A field containing a value for direct addressing. In indexed sequential access 
method (ISAM) files, data management introduces pointers between records to 
provide for maintenance of logical sequence of records. 

record 
The collection of contiguous characters designated by the user to data 
management as such, for handling as a unit. Record size must not exceed block 
size. 

volume 


The largest physical unit for data storage, such as a tape reel or disk pack. 
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1.3.2. Punched Card Files. 


A. punched. card file consists -of a card deck, input via a: reader, or output via a punch: 
Records 'can,comprise either.a portion of a card or a complete card. The records are made 
up of fields of related characters..Punched card files must be iar? as oucuataae files 
inanaled: one record ata time in. sequential order). ae if : 


You must not confuse a deck of eards to be handled asa data: aanaoeients cari file with 
control stream cards or with data cards embedded in control streams. You must place the 
data management deck in the card reader when there is a console message calling for 
assignment of the reader to the program. You may begin the deck immediately with a data 
card, but you must end it with an end-of-data card (/*). You cannot place an end-of-data 
card within the deck. 


Details.of punched card records and files are presented in Section 2. 


1.3.3. Diskette Files 


Diskette files are sequential, ‘unblocked files processed similarly to card files. In fact, 

diskettes are intended as rapid replacement media for card. processing equipment. Each 
diskette is a single-sided, single plate disk with tracks containing fixed sectors. Records 
are recorded on the tracks, one record per sector. (Sections 4 and 5 discuss the ee in 
more detail.) 


1.3.4. Printer Files” 


Printer files include standard text, listings, forms, and similar printed ouptut. The files are. 
composed of individual records that are formed in an output area or-work.area by your - 
program and then output to the printer in increments of one record (line). The file is 

output, character by character, in a serial manner. When the printer buffers are loaded, 
the line is then printed. This process repeats, each line in succession, until the entire file 

is printed. A printer record can also contain certain control characters which, although 

part of the output record, are not printed. The control characters allow you to advance the 
paper to a home position, specify a procedure in case of overflow, or select a number of © 
lines to: be skipped: by the printer. Section 6 gives details on printer files and Fecords; i 
peciony 7 BescniDes the uses of control characters. teas 


1. 3. 5. Magnetic Tape Files 


Magnetic fape files are also saquanitial files, and can span more hans one We lUiiée fred: ; 
Each magnetic tape file is identified by two file header labels; each volume of the file has. 
a volume label. Because most magnetic tape files can be read in both a forward and 
backward direction, the file labels are placed both at the beginning and at the end of each 
of these file levels. — 
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Figure 1—2 illustrates the relationship of the various elements of a magnetic tape file. The 
volume label (VOL1) has a standard system format that describes the contents of the tape 
volume. The two file header labels (HDR1:and HDR2) also are in a standard system format. 

User header labels (UHL), which are optional, may be in a standard format or one that you, 
as a user, can structure. A tape mark: is next in the sequence, and acts as a delimiter to 
indicate that data blocks or records follow.: After the data, another tape mark, -two end-of- 
volume (EOV) labels, optional user trailer labels (UTL), and two more tape marks are 
provided as delimiters..A. complete description of the magnetic tape file organization and 
conventions is: eae in Section 8; Pppendix E describes the labels for a ede tape 
files. : 3 oe 









TAPE MARK TAPE MARKS 







“BLOCKS © 


LEGEND: 


rr, 
VOL1 Volume Label i 
HDR1 File Header Label 1 C ~IRECTION OF OVEN, FORWARD READ se 
HDR? File Header Label 2 DIRECTION OF MOVEMENT, FORWARD READ .: ; : 
UHL User Header Labels (optional) 
EOV1 End of Volume Label . . 4 . 7 9h ' ee wee 
EOV2 _ End of Volume ‘Label 


UTL User Trailer Labels (optional) - . 


. Figure 1—2. Magnetic Tape File: Organization 


1. 3. 6. Disk Files: 


Provisions for disk files differ. ee fhiosé: fr Soquel devices in that there are several 
data management programs from which to choose. You implement your choice by — 
selecting, one of several operation codes at the point in your program where the DTF 
(define the file) procedure (proc) is coded. You must consider the services offered by the 
programs to determine which is best suited to your needs for the particular file. (There is a 
certain amount of overlap in the services available, so it is possible for you to meet a 
particular need through either of two programs.) The desire for rapid storage and pewena | 
is eae Paramount: In this Context ‘Several considerations are pertinent: 


“ds aero: bye fisctied? 
= Is appending new data to a series satisfactory, or are insertions necessary? 


# Are direct addressing or sequential access, or both necessary? 
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2 Is reading or writing blocks sufficient, or is assistance with records needed? 


To’satisfy these questions, detailed descriptions of the disk file services are presented in 
Sections 11 through 13. ase: 


1.3.7. Paper Tape Files 


Punched (or perforated) paper tape files are handled at the logical record level by a paper 
tape data management system described: in Section 17. The system provided by OS/3 
includes macros, transients, and processing modules with which you can define paper 
tape files and read and write data on paper tape. Translation and fete CUOMTe eee Le 
capabilities are provided. ; 


1. 4. PROGRAMMING FOR DATA MANAGEMENT a 


All users of 08/3 must “eiapley the conventions established for aesgeanad sisting files: 
and new files in the job control stream. In gang data ence. you must also cone 
appropriate ye in your BAL pica m. 7: vst 


z= By issuing a DTF deciaiatve ‘macroinstruction Baovideds eee dats managenbat. you: 
cause a DTF table to be created in a data area. By using keyword parameters, you 
describe the file and provide addresses of buffers and work spaces. You must also 
indicate your desire to handle all returns inline, or you must give the address of your. 
routine for aceepiag conmro! when errors or excepuenae Occur: 

Ei By using ordinary’ assembler instructions, you: must reserve - éuificiant amounts of 
main: storage buffer space. and WORKS aCe, and you must provide the ied onaas ae 
routine. a 2 rarer 


Ee By issuing imperative macroinstriictions arevided: with each ‘access method. en, 
_ request data management to perform specific file- “prosessing functions. a 


= You must realize that general registers O, 1, 14, and 15 are loaded by the imperative 
macroinstructions before the contents of your registers are saved. You cannot afford 
to have vital data in these registers when you call on data management. ~~ 


= — You must provide a 72-byte register save area. The address of this area can be placed 
_in the DTF by specifying the SAVAREA keyword parameter, common to all DTFs. 
Failing to do this, you must provide the address in register 13 when you enter each 
data management unpernts macro. | | 


= The agiage area you specify with the SAVAREA keyword parameter is often: useful to 
examine in snaps or dumps of your program region. It comprises 18 full words, the - 
first three of which are used by data management. Following these is a display of full 
words for 15 of the general registers, presented in the following order: 14, 15, O, 1, 2, 
and so on, through 12. Register 13 is not included. 
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1.5. OS/3 DATA MANAGEMENT ENHANCEMENTS 


OS/3 data management departs from traditional data management | ayeiems in several 
areas. -s 


1.5.1. ISAM Files 


In OS/3..ISAM: files, inserted records are placed in overflow blocks, forming chains 
between individual prime records. This causes all data records to remain where originally 
placed and eliminates time consuming record pushdown. Moreover, the stability of records. 
makes it possible to offer direct addressing to. every record, a convenience for MNOSe who 
can benefit from this feature. : 


The ISAM program can also operate on files where the key index structure is never 
formed. This precludes the use of keyed instructions, but leaves the rest of the repertoire 
operative. The ISAM load is still effective for file creation. The resulting file is men 
suscentnit: to Sed uenti: ane direct: access without ie 


Eliminating the index does not neeeetate the ability to insert. records. The position for 
insertion cannot be reached by a key search. However, both direct access and sequential 
progression are available to reach any record so that a new record may be inserted after it. 


1.5.2. SAM and DAM Files 


The flexibility of sequential access method (SAM) and direct access method (DAM) 
processing. has been augmented in OS/3 by provision of a DTFNI macroinstruction and 
processing module. This module supports. an. extended repertoire of imperative 
macroinstructions applicable to a file described by the DTFNI macroinstruction. 
Combinations of SAM and DAM imperative macroinstructions may be used; NOTE and 
POINT imperative macroinstructions are provided. There is also provision for partitioning a 
file, using different. block specifications for each partition. These are supported by 
partition-relative block addressing. 


1.5.3. IRAM Files - 


The indexed random access method (IRAM) is an access method in OS/3 for handling disk 
files and is intended for use by programs written in RPG II language, the sort, and data 
utilities. The functionality of IRAM is equivalent to that provided by OS/3 ISAM and 
ASAM, and by the OS/3 nonindexed access disk methods SAM and DAM (relative record 
addressing); however, those modules (ISAM, ASAM, SAM, and DAM) are considerably 
larger. The. IRAM processor cannot access disk files that have been created by other 
access methods nor can IRAM files be processed by other OS/3 disk access methods. 
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1.5. 4. -MIRAM Files 


‘The. @ultigis indexed. sender: access sated (MIRAM). in 0S/3 is tised! ior pandineg 
‘sequential, relative, and indexed files in programs. These programs are: written in the 
OS/3 version of the 1974 American National Standard COBOL, and for sequential and 
relative (direct) files in programs that are written. in FORTRAN IV. MIRAM provides the 
same functions as those provided by OS/3 ISAM, ASAM, IRAM, SAM, and DAM disk 
access methods. The MIRAM processor can access only MIRAM and IRAM characteristic . 
files that it has created or IRAM files created by the IRAM processor. It cannot access disk — 
files that have been created by other access methods nor can MIRAM files be processed 
by other OS/3 disk access methods. MIRAM files, however, can be processed by veng the 

sonar? and data utilities programs. 


1.5.5. Error and Exception Returns 


OS/3 data management differs somewhat from other data management systems in its © 
method of returning control to your program. Control is always returned, whether or not 
an error or exception has been detected. A reply field is always set'to indicate the nature 
of the exception. If the function is executed with no defects, control is always returned 
inline to the instruction following the macro call. If you provide the address of an 
error/exception routine in your DTF macroinstruction, control is returned to that address 
on all occurrences of errors or exceptions. In the absence of this address, all returns are 
made inline (register 14 always contain the inline return address). Appendix B eescunes 
the error and exception handling features of OS/3 data management. 


Because data management interprets a zero value in the DTF error field of the DTF file 
table as the nonexistence of an error routine, you must not locate your error routine at 
location 0 relative to the load medue 


Errors occurring during file extend operations are always associated with inability to 
acquire output space for a buffer and consequent loss of output data. On extend failure 
errors, file extend procedures now minimize loss of output data to one record. — 


1.5.6. Disk Flexibility and Hardware Constraints: 


The obligation to handle disk devices with different characteristics has influenced the 
design of OS/3 data management. It was considered desirable that the disk file processing 
modules should be independent of the disk type used and should present the same 
interface to you. As a result, OS/3 data management requires, throughout, that all blocks 
in a track or partition be uniform in size and format. On the fixed-sector disk devices, it is 
also necessary that all blocks be multiples of 256 bytes. Furthermore, spanned records 
(those extending beyond a block boundary) are not supported. oe Ges . 


Consequently, during sequential blocking of records, block filling continues until a 
submitted record will not fit in remaining block space. At that point, the full-size block is 
written to disk, and the rejected record is used to begin the next block. 
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The fixed-sector disk does not provide an RO record for identifying the portion. of track 
devoted to useful data. Furthermore, the hardware search interrogates the first n bytes of 
-. every 256-byte sector. These characteristics cause some restrictions of relative-track-DAM 
.. functions. When employing the WRITE,AFTER macro, you must fill each track because the 
unfilled portion is:not identified. When employing keyed operations, you must use a block 

size. of 256 bytes; otherwise, false internal hits could be made in blocks of 512 pytes and 
other ee of 256 bytes. 


1.5. 7. Shared Data Management Modules 


Under OS/3, all data management modules are shared- code modules. There is only one 
data management module for each access method and when a particular access method is 
requested by a program, one copy of the corresponding module is loaded into main 
storage. This module is then used or shared by all programs requesting the same access 
method. 


1.6. DATA MANAGEMENT/USER INTERFACE 
| The jaterface between. you and data management ¢ consists of: 
a "Declarative macroinstructions - 


. imperative macroinstructions 


1:67: Declarative Macroinstructions | 


Your program must inform the system of the parameters, special conditions, current 
status, and. options pertaining to a file. You must include a declarative (file definition) 
_macroinstruction for. each file required by your program. As implied by. the term 
declarative, these macroinstructions generate nonexecutable code, such as constants and 
storage areas for variables. Therefore, you should separate these macroinstructions from 
the inline file processing coding. The declarative macroinstruction and the selected 
keyword parameters in the operand define the file. The first three characters of the 
operation code must be DTF. The last two characters usually indicate the type of device or 
method of. accessing. A keyword parameter consists of a word or code mmeaareny 
. followed by an equal (=) sign and one as 


: The jermat of the declarative iacrolnstniccionis: 





‘OPERAND 







A OPERATION A 





filename keyword-1 =Xx,...,keyword-n=z 
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The symbolic name of the file must appear in the label field. The name can have a 
maximum of seven characters and must begin with an alphabetic character. The 
appropriate DTF designation must appear in the operation field: The keyword parameters 
can be written in any order in the operand field and must be separated by commas. 
However, a comma must neither be coded in column 16 of a continuation line nor follow 
the last keyword of a string. Appropriate assembler rules regarding macroinstructions 
apply to blank columns and continuation statements. Register numbers are specified to the 
data management declarative macroinstructions (DTF) by enclosing the’ number in 
parentheses. Certain DTF parameters can be changed at run time via the data definition 
job control statement (DD). (See Tables 3—1, 7—3, 9—1, 11—3, 13—1, 13B—1, 15—1, 
15—2, 15—3, and 17—1.) Bs ee at eM le 
The DTFs may have the following forms: 
=» . DTFCD 
~~ Defines-an input, output, or combined punched card file. re ea 

=» DTFDA 

Defines either an input or output direct access disk file. 
=  DTFIR 

Defines input or output indexed or nonindexed IRAM disk files. 
= DTFIS 

. Defines an indexed sequential disk file. 

= DTFMI | 

Defines an input or output indexed or nonindexed MIRAM disk files: 
=e DTFMT 

Defines an input, output, or in/out magnetic tape file. 
s.~ DTFNI - 

Defines a nonindexed input and output disk file. 
= ~DTFPR 

Defines a printer output file. 
= = DTFPT 


Defines an input or output paper tape file. 
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= DTFSD 
Defines an input, output, or combined sequential access disk file. 
C “DPCA oe 


Similar to z a 1 DTF macroinstruction, but detines a partition of a disk file rather than the 
entire file. 


1.6.2. Imperative Macroinstructions 


Your program must be able to communicate with the data management modules in order 
to process files that have been defined by declarative macroinstructions. Imperative (file 
processing) macroinstructions included in ‘your program communicate with the transient 
routines and logical |OCS shared-code modules. The imperative macroinstructions are 
expanded as inline executable code. Not all macroinstructions are available for use on all 
devices. Some are specifically input-type macroinstructions and cannot be used for a 
device that is exclusively used for output; the opposite is true, also. 


The format of the imperative macroinstruction. is: 





A OPERATION A OPERAND 


A symbolic name can appear in the label field. The name can have a maximum of eight 
charcters and must begin with an alphabetic character. The appropriate verb or code must 
appear in the operation field. The positional parameters (as signified by the name) must be 
written in the specified order in the operand field and be separated by commas. When a 
positional parameter is omitted, the comma must be retained to indicate the omission 
except in the case of omitted trailing parameters. Appropriate assembler rules regarding 
macroinstructions apply to blank columns and continuation statements. 


1.6.3. Assembler Rules for Operand Field 


The operand field of a macroinstruction begins in column 16 and may not extend beyond. 
column 71. An operand may be continued onto the next line by inserting an arbitrary 
nonblank character in column 72. Each continuation line starts in column 16. 


The operand field is terminated by the first blank which is not enclosed ‘within 
apostrophes. As operand specification is usually completed before column 40, columns 41 
through 71 are available for comments, but at least one blank space must occur between 
the end of operand specification and the beginning of the comments. 
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Comments are not continued by the insertion of a nonblank character. in column. 72. 
Lengthy comments can be entered by coding an asterisk (*) in column 1. You will note the 
applications of these rules’ in the programming examples throughout this manual. 
Operands may be continued onto the next line by placing a comma after the last operand 
on the first line and a nonblank character in column 72. However, if you omit the comma 
and at least one blank exists between the last operand on the first line and the nonblank 
character in column 72, the second line of operands is treated as comments. Because the 
second line is treated as comments and not as part of your operand specification, the 
assembler does not. flag the missing comma as an error. Up: to: two: comment lines are 
permitted. 


1.7. RELATED OS/3 SOFTWARE 

Several OS/3 software components are indirectly. involved with data management, while 
others eee functions related to and required for program Sa TGR omen 
include: | fo nee ae oe 

B Sam service programs (SSP) 

w Job control 

w Supervisor 

w Linkage editor 


= Data utilities. — . at ae 


1.7.1. System Service Programs (SSP) - 


The. service programs. provided to prepare disk and magnetic tape files to accept data 
records and blocks are the disk prep. program and the magnetic tape Pree: Bregtan 


The disk prep routine ers a surface analysis for the disk iracks and assigns Blernate 
tracks if defects are discovered. The disk prep also establishes a volume. table of contents 
(VTOC) for the device so that files can then be placed on the disk. ; 


The magnetic tape prep routine prepares magnetic tapes in standard label format by 
writing the initial volume label, dummy file header label, dummy file trailer label, and ee 
marks. | . > nee 


Other system service programs relies dump» routines in ‘non- narrative or r narrative. 
formats. The SYSDUMP and JOBDUMP routines provide the resident shared-code 
directory and the preamble EXTRN table in narrative format. 


These routines are described in detail in the system service programs (SSP) user: guide, . 
UP-8062 (current. version). 
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1:7.2. Ons Control 
The main teanctione of job control, as related to data saunagernantlcs are: 
' / Allocation of f required peripheral devices | | 
_ “File control block (FCB) management 
. : ‘Catalog management allowing automatic: identification of files by name - 
= Loading printer vertical format buffer (VFB) and load code buffers 
# Defining software facilities (SFT) needed to support the user program 
: MoeN ying: OLE eases at run- time- {DD}. 
Pariaheral aagics are desianied through job cential statements that ssaniy iogicals unit 
numbers, alternate device types, and information about the file. These job control 
statements include: ae 3 oe 
// DVC Statement assigns device number. 
// NOL Statement describes tape and disk volumes. 
// EXT Statement provides disk extent information. ae ae aR . a 
// LBL Statement provides additional tape and disk identification information. | 


// LFD Statement links the file defined by the DTF macroinstruction with the ule and 
device information in the control stream. — | 


Each part of this manual that deals with a particular access method or device type 
providés you with job control stream examples that illustrate the relationship between data 
management entries coded for program assembly ang the eee control stream Statements 
inet ‘control the program. 


A separate file control block is maintained automatically in main storage for each active 
file. This block contains all descriptive He alee about the file and is used for reterence 
when the file is being accessed: | : 


0$/3 automatically loads the data management modules needed by your job. However, if 
you have written your own shared-code modules, you must use the SFT job control 
statement to identify and load these meee SFT statements are effective only during the 
job-step in which they are Spocitied:. Petes | e | 


For aptalls on OSs/3 _ cone refer to the job control user guide UP- 8065 (current 
version). 


= PIOCS 
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1.7.3. Supervisor 


The .supervisor. provides the greatest amount of support for the user piegramn and data 
NAnegement This Support includes the foro ing: 


Those macroinstructions and routines that schedule and monitor execution of channel 
programs, controlling the actual transfer of physical records between external sources 
and main storage. These routines also provide for device-1/O error recovery: 

m Transient scheduling 


The routines that retrieve transients from auxiliary storage and bring them into main 
storage for execution. These include file open and close routines. 


= Operator communication 


The routines that handle the communications concerning volume mounting requests, 
tape mount requests, etc. 


= @€File protection 

Protection of files and records during shared file processing. 
= §€ Timer services 

Used as a reference for computing run time, scheduling, etc. 
= Disk space management 


Routines for allocating space to disk files and maintaining space accounting through 
standard procedures for updating the volume table of contents (VTOC). 


a System Access Technique (SAT) 


An input/output control systems that provides a standard interface for tape and disk 
subsystems between OS/3 data management and the PIOCS. 


For details concerning the supervisor, refer to the supervisor user guide, UP-8075 (current 
version). 


1.7.4. Linkage Editor 


The linkage editor is a system service program that constructs a load module from object 
modules. The linkage editor control statements that define the load module are contained 
in the job control stream beginning with a LOADM control statement and terminated by 
another LOADM control statement or by an end of data (/*) job control statement. For 
details concerning the linkage editor, refer to the system service programs (SSP) user 
guide, UP-8062 (current version). 
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1.7.5. Data Utilities 


‘The OS/3 data utility and service routines are provided to assist you in manipulating data 
files and preparing card decks. Your use of these routines requires only a minimum 
amount of programming effort. You simply code the appropriate job control statements, 
together with utility and data statements or control specifications, to exchange information 


with 0878, Submit Parameter: and start your is 


The 08/3 data iitilities anid service routines are described in detail in the data utilities 
user guide/programmer reference,.UP-8069 (current version): | 


Sn, 


PART 2. CARD, DISKETTE, AND PRINTER FILES 
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2. Card Formats and File Conventions 


Pe GENERAL | 

This section describes the data formats and file conventions that apply ‘ciihe card reader 
and card punch subsystems supported by the SPERRY UNIVAC 90/30. System and the 
OS/3: 

= SPERRY aie 0604 Card Punch Subsystem 

= SPERRY UNIVAC 0605 Card Punch Subsystem 

m SPERRY UNIVAC 0716 Card Reader Subsystem — 

# SPERRY UNIVAC 0717 Card Reader Subsystem 

Zz | SPERRY AAG 0719 Card pedget Subeyeiom 


For ‘the functional characteristics of these subsyatems, refer to 0 Appendix AL 


2.2. FILE ORGANIZATION 


Your punched card decks may include a start-of-data job control card at the beginning and 
must include an end-of-data job control card at the end of the card deck (Figure 2—1).. 
Punched card files can be input (card read), output (card punched), or combined 
(read/punched). . ‘ ne . de esas 


The basic punched cards for subsystems supported by OS/3 are standard 80-column, 12- 
row rectangular tab cards. However, optional hardware features, available on both 0716 
and 0717 card readers, allow reading of 51- and 66-column stub cards. The 0716 is 
capable of reading 96-column card data files. 7 sass 
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END-OF-DATA JOB 
CONTROL CARD 








OPTIONAL 
51-COLUMN 


START-OF-DATA JOB 
CONTROL CARD 


ene END-OF-DATA JOB 
CONTROL CARD 






/ 
COMBINED FILE / 
(ALTERNATING DATA 170 WGAHDS Sees ns: 
AND BLANK CARDS) EACH CARD IS 
a eee . A SEPARATE ieieienmamatee : 
RECORD / 


START-OF-DATA 
JOB CONTROL CARD 
(OPTIONAL) . 


Figure 2—1. Typical Card File Structure 


2.2.1. Card Input Files 


The card reader handles fixed-length unblocked records, which always have the same 
length for your entire file. This length is equivalent to the value you: selected for the 
BLKSIZE keyword parameter of the DTFCD macroinstruction when defining the file. Figure 
2—2 illustrates the fixed-length unblocked format related to card input files; the same 
format is used for combined files (8.2.3). me agit es 


record n 


NOTES: 





1. The record length, A, must be an even number of bytes, at least as many as specified by the BLKSIZE keyword 
parameter. ; 


2. The |/O area must be aligned on a half-word boundary and comprise an even number of bytes. 
3. When 51-column stub cards are processed, the BLKSIZE keyword parameter may specify a 51-byte length, but the I/O 


area must be 52 bytes in length. A work area may be 51 bytes long. 


Figure 2—2. Fixed-length Unblocked Record Format for Input and Combined Card Files ae 
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2.2.2. Card Output Files 


The card punch files (output) consist of data that is formed into: physical records, usually in 
the I/O area, and then output to the card-punch, where the records are punched in the 
standard 80-column format. The cards are then accumulated in a stacker, which keeps 
them in sequence. 


2.2.3. Combined Files 


Combined read/punch files are allowed only where the optional read/punch feature is 
installed as part of the card punch. This feature allows you to read cards and punch cards 
in the same file (deck) on a single pass through the card punch. Reading and punching of 
cards can be accomplished in the following ways: 


= Data can be read from a card then punched on the same card. ‘This requires the 
nonoverlap mode of processing (3.3). 


= A card deck containing alternating punched and blank cards can be entered; each 
punched card is read and data is punched on the blank card following. The overlap 
mode of processing must be specified (3.3). . 


= Punched cards and blank cards can be grouped; the punched cards are then read, and 
the following group of blank card is punched with the new data. The overlap mode of 
processing must be specified (3.3). 


2.3. RECORD FORMATS 


2:3.1. Start-of-Data Job Control Statement (/$) — 


Data management does not check for a start-of-data card. For consistency, you may 
choose the /§$ card convention as a card file identification. If you do so, your program 
should include a check for this card. 


2.3.2. End-of-Data Job Control Statement (/*) 


Data management checks for an end-of-data card when you are reading cards. The format 
of this card is identical to that required by job control. The first two columns. contain /*. 
When this configuration is sensed, control is transferred to the end-of- file address 
specified for the file. When an output file is punched, the end-of-data card is not punched 
by logical IOCS. You must supply the end-of-data card for input and combined files. 
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2.3.3. Card Punch Records 


You may form card punch records either in the |/O area or in a designated work area of 
main =rOrage: The records, illustrated in Figure 2—3, are of three. types: 


- “up ed-lenatht Peconds 
m  Variable-length records 


Ei Undefined- length Records 


Fixed- Bah tod 










; : s < 


Undefined 


Variable-Length eee ee ee Oe ae ( 





LEGEND: 


b Block size field, four bytes 
mo Record length field, two bytes, binary 
Reserved (two bytes); may be any two characters chosen by ‘the user : 


u 

A Data record length 

C Variable record length 

D Record size field 

F/O area layout. ‘ 
NOTES: 


1. An 1/0 area must be so aligned that the first character to be punched falls on a half-word boundary. 

2. Record length, as a binary number, must be placed in the first two bytes of the record length field (r) before punching a variable- 
length, unblocked record. 

3. Aneven number of bytes should be allocated for data in |/O areas, even though an odd number of columns are to be punched. 
The I/O areas for a file with an odd block size should provide at least block size+1 bytes. 


Figure 2—3. Card Punch (Output File) Record Formats 
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oer © Function and Operation of 
Punched Card SAM 


{ 


3.1. GENERAL 


The OS/3 includes data management modules that you can use to move and manipulate 
sequential access method (SAM) card reader files, card punch files, and combined 
(read/punch) files. These modules allow you to configure your program for each particular 
application and related device types. 


This section contains a brief functional description of punched card SAM operation for 
input files, output files, and combined input/output files. Following the functional 
description is a detailed explanation of the declarative macroinstructions that define the 
three types of files. The section concludes with detailed descriptions of the imperative 
macroinstructions that initiate, conduct, and terminate file processing. 


3.2. FUNCTIONAL DESCRIPTION 


3.2.1. Punched Card Input 


The card reader is a unit record device and is connected to the integrated peripheral 
channel or to the multiplexer channel, if several relatively slow peripheral devices are to 
share I/O jointly. The punched card file comprises data in the Hollerith punched card code 
(Appendix C). The cards are usually divided into fields; these files, in turn, are combined to 
form physical records. 


You define, to the system, the type of file, structure of the data, and the operating 
environment in which your file will be processed through a define the file (DTFCD) 
declarative macroinstruction. At system installation, the system macro library file 
(SYSMAC) is loaded with source code modules that are common to several machine 
operations. These modules include data management modules that are common to several 
device types and access methods. 


When assembling the program, you define the files (input, output, or combined) used in 
the operation through the DTFCD macroinstruction. The source modules for the particular 
data management operation are called in from the macro library during program assembly 
by using imperative macroinstructions which place the modules in your program as inline 
code. Each macroinstruction available for punched card file processing is described in 
detail in 3.3 and 3.4. 
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3.2.2. Punched Card Output 


The punched card output records are constructed in the |/O area or a designated work 
_area. Processing data and creating an. output on punched cards are similar to the 
procedure described in 3.2:1 except that the CNTRL macroinstruction can be used with the 
0604 Card Punch Subsystem (0604. card: punch). 


lf the punched card deck is to be inserted in a program, you must punch a start-of-data 
(/$) job control card and an end-of-data (/*) job control card and add these to the 
beginning and end of the punched card deck. 


a, 
é 
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DTFCD 
| _ (card) 


3.3. DEFINE A SAM CARD FILE (DTFCD) 
Function: 


The DTFCD declarative macroinstruction is required for you to define punch card files 
that are accessed by OS/3 SAM. Following is a listing, in alphabetic order, of the 
required and. optional keyword parameters that might appear in ‘the operand of the 
DTFCD macroinstruction. A summary of the keyword parameters is provided in Table 
3—1. 


A comma is shown preceding. each. keyword parameter except the first, to remind you 

that all keywords coded in a string must be separated by commas. However, a comma 
~. must neither be coded in column 16-of a continuation line, nor: Solow: the last 

keyword in the string. Refer. to the coding examples which follow. . 


Format: . 


LABEL A OPERATION A OPERAND . 


filename DTFCD [ASCII=YES] 
_ |. AUE=YES] 
-[, BLKSIZE= n] 
[ ,CONTROL=YES] | 
[,.CRDERR=RETRY] | 
iE, EOFADDR=symbol] 
“ELE ERROR=symbol] _ 
,LOAREA1=symbol 
L |OAREA2=symbol] 
--[, LOREG=(r)] 
Eee we 6 ei. “cd [,TBL=symbol] . 
ee ae e ~|,MODE= ( BINARY) 





TRANS 
LOPTION=YES]. 
[,ORLP=YES] | 

_|. [,OTBL=symbol] . 
_ LOUBLKSZ=n] - 
,RECFORM= 





UNDEF _ 
VARUNB ) | — 


| eee a ) 


-LSAVAREA=symbol]: ~ 


aoe { AN ty) 
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LABEL A OPERATION A OPERAND 





filename _TYPEFLE= | | 
(cont) ‘OUTPUT 

__{ CMBND 

LWORKA=YES] _ 
Keyword Parametot ASCII: 
ASCII=YES. ss Ene : 

Specifies preepseing in American Standard ‘Code ok Information Interchange 
(ASCII). oe 3 


For input files, you must specify this parameter if you desire your card data to be 
translated into ASCII code for internal: procescing and oe 


. For Sutput files; you must specify this sarcineier if internal processing i is:in ASCll and 
you desire output in Hollerith punched. card code (Appendix: C). 


The keyword parameter MODE should be written as MODE=STD if this parameter is 
supplied. 


Keyword Parameter AUE: Aas 


AUE=YES oa -_ me se N 
Inhibits data management | error processing when validity check errors are 
detected on nonbinary input files. 


In punched card input files, a validity check error (also termed a unique unit error) is 
the occurrence of more than one punch in rows 1 through 7 of any column in a card, 
and usually indicates a mispunch. Each time a validity check error is detected, the 
operator receives a PIOCS message at the system console indicating the problem. The 
card containing the error is the last card in the stacker. The operator has three 
options: He can place the error card in the input hopper and reply ‘‘R’’ to reread the 
card, or he can reply “I or “U”, to indicate that the error is to be ignored or is 
unrecoverable. If you have specified AUE=YES, and the operator replies “‘l’’ or ‘““U”, 
data management does not branch to your error routine. The error card is skipped (not 
passed on to the user). . . 


On the other hand, if you do not specify AUE=YES and a validity check error is 
detected, data management branches to your error routine if the operator replies “U”. 
When your error routine receives control, data management will have set the unique 
unit error flag (byte O, bit 2) of filenameC in your DTFCD file table.. Refer to Appendix 
B. Data management ignores the AUE keyword parameter if 8413 diskette files are 
used. a, ae an 


Keyword Parameter BLKSIZE: 


BLKSIZE=n : 
Specifies the length of the 1/0 3 area in bytes. If the records in a file are variable 
length, 7 specifies the maximum size for records. For variable, unblocked records, 
n includes the block size and record length fields. 
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The user can specify BLKSIZE=1 to BLKSIZE=96 to read from 1 to 96 columns of 
a 96-column card. 


A user program that specifies BLKSIZE=1 to BLKSIZE=80 can read from 1 to 80 
columns of 96-column cards. A program that has a BLKSIZE of 1 to 80 and that 


has been used. with 80-column cards, in any mode except es can read 96- 


column cards with no program changes. 


A program that specifies BLKSIZE=1 to BLKSIZE=96 to the DTFCD proc call can 
be used to read up to 96 columns of a 96-column card. Such a program can also 
read up to 80 columns of 80-column cards. The DMCS will blank out (insert the 
appropriate blank character, based on data’ mode) bytes in the user’s |/O and 
work areas for columns beyond 80. At OPEN time, DMCS checks for 80-column 


--cards being read: with BLKSIZE ‘from 81 ‘to 96. If such a condition exists, a 
Z messeue: is Issued to the operator with a peguines reply: 


If einitted: the block size is determined from the keyword parameters MODE, 
-RECFORM, and oe - _ 


Keyword Parameter CONTROL: 


CONTROL=YES 


Specifies that your program will issue one or more » CNTRL inaperative macros to 
control stacker selection on the O604 card punch; used only for output or 
combined card files. 


~The use of the CNTRL macro, which applies neither to input card files nor to the 0605 
card punch, is explained in 3.4.4. If you specify CONTROL=YES in the DTF for an 
input file, the parameter is ignored, and:a diagnostic message: is ee. in the DTF 
expansion in your assembly listing. 


Keyword Parameter CRDERR: 


CRDERR=RETRY 


Specified if card punch error recovery should be attempted on ee count errors 
for 0604 and 0605 combined read/punch files or on the 0604 card punch output 
- files with stacker selection. Error cards are automatically selected-into the error 


- select stacker. If error-recovery is not successful; the logical IOCS returns control 


to the address of the user’s error. routine (ERROR). If keyword parameters 
CRDERR and ERROR are not specified, the card system returns to your program 
inline when a punch error (hole count error) is encountered. See 3.6.2. 


Error recovery is provided for hole-count errors on 0604 combined read/punch card 
files, 0604 card output files with stacker selection, and punch check-errors on O605 
- combined read/punch card files. If the 8413 diskette is used, the CRDERR= RETRY 
porarnet el: is” ignored. — 


Keyword Parameter EOFADDR: 


EOFADDR=symbol 


Specifies the address to which control is transferred when the end-of-data card 
is sensed. This keyword parameter is required for all input and combined files. 
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Parameter ERROR: 


ERROR=symbol 


neywere 


Specifies the address of. your error handling routine. When a fatal hardware or 
detectable logical error occurs ona file, you may have control transferred to a 
special error handling routine. If not specified, errors return Ne (see 3.6 and 
Appendix B). ; 


Parameter IOAREA1: _ 


l|OAREA1 =symbol 


Specifies the address of an 1/0. area that each input or output file 1 must have 
reserved for its individual use. Keyword parameter IOAREA1 specifies the input 
area for a combined file; IOAREA2 must. also be used to specify the combined 
file’s output area. |/O.areas must contain an even number of bytes for data to be 
punched or read. Odd numbers of columns can be read or punched. If the 


_BLKSIZE specification. is an odd number of bytes, the |[/O areas must be at least 


Kevward 


BLKSIZE + 1 bytes long; this means, for example, if you are using all of the 51- 
column stub card and have therefore specified BLKSIZE=51, that the length of 
the storage area you define for IOAREA1 must be 52 bytes. The first data byte 
(character read or to be punched) must be aligned on a half-word boundary. The 
length of the area is specied es the keyword Parameter BLKSIZE. 


Pa rameter IOAREA2:. 


Ra cieh creas ibs 


May specify a secondary :|/O area for standby processing; must be used to 


- ‘specify the output area for a combined file. You must allocate I/O areas that 


Keyword 


provide an even number of bytes of data. The ust data a byte: must be allgne? ona 
half-word boundary. 


Parameter IOREG: 


1IOREG=(r) 


Specifies the number of the general register (2 through 12) used to haters 
current data. If SAVAREA is specified, register 13.may be used: for IOREG. If a 
work area is not required, this keyword parameter must be specified when there 
are two |/O areas. This parameter may not be specified if either a work area or a 
combined file is specified through the DTFCD macroinstruction. oe not specify 


-~WORKA if this parameter is saasioh 


Keyword 


Para meter ITBL: 


ITBL=symbol 
-Specifies the addrass. of 1 ie 256- inte i anelation table in your problem program 


when records in an input or combined file are to be translated on input. If the 


keyword parameter MODE=TRANS is se mG meyers poe ITBL 


must also be specified. 


Oey, 
f 4 
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Keyword Parameter MODE: — 


This keyword parameter is used to specify the input/output mode of the file and is 
- required as part. of the DTFCD macroinstruction. There are four forms of the eRe VOOrd 
parameter which can be used with all types of files: 


MODE=BINARY 
This form is used for safd read on the a6 reader in singe mode or for cards 
read or punched on the card punch in column binary (image) mode. An !|/0O area 
of 160 bytes is required for one 80-column card. 


_ The binary mode is not: available for 96- column cards. This perarieter is ignored 
if the 8413 diskette is used. 


Mov EH & 
On the card punch, this form must be specified for cards read or punched in 
ucempressed? code. An |/0-area: of 80 ies is requived ge one 80- column card. 


MODE= STD 
Should be specified for cards to be read or punched in EBCDIC. This keyword 
parameter must be specified if the ASCII=YES : eat se is specified. if no 
MODE. keyword is eee ale option is  Besumed:: 


MODE=TRANS 
You should specify this option to have cards read in EBCDIC and translated by © 
your ITBL translation table, or translated by your OTBL translation table and then 
punched in EBCDIC. Each position of PYOUr 256- nove translation table contains a 

_  bit- Rarern yeu nave ae es to it. 


On raading a byte or card column in the record to be translated, data 
management places into the receiving byte of:your I/O area the bit-pattern it 
‘finds in the position of your translation table which corresponds to the position 
which the bit- or hole-pattern to be translated occupies in Table C—1 (Appendix 
-C). For example, on reading 12-0-9-8-1 hole-pattern, which occupies position O 
in the EBCDIC column labeled Hollerith Punched Card Code in Table C—1, data 
~ management will place into your I/O area the bit-pattern it finds in position O of 
-your ITBL translation ‘table. If you move to your I/O or work ‘area the bit-pattern 
which occupies position 1 of your OTBL translation table, data management will 
punch the hole-pattern (12-9-1) which occupies position 1 in the EBCDIC column 
labeled paueuEn Punched shakek Code in Table C—1, an so on. 


Do not use the Hollerith Punched Card Code column in the ASCII portion of Table 
C—1 for this translation table feature. 


por Faramietel OPTION: 
OPTION=YES 


Specifies. an Aational: file: one whieh you anticipate will not Einvamiably. be required 
for every execution of your program. 
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When the OPTION keyword parameter is used, optional file processing is performed 
by data management 


= if ihe OPT posit onal parameter is aneluded in your pvc job Sonitral: statement 
and the device is not avaialble at execution time; or 


= when no device is assigned to the file PY veut job control statements (i.e., no 
DVC-LFD device eeslgnnent set). 


Optional file. processing: 


= For an input. or, combined file, which .you issue a ‘GET ‘imperative 
macroinstruction, data management branches to your end-of-file routine 
(EOFADDR). No cards are read. You should close the card file. 


m For an output..or combined file, if you issue.a° PUT or a CNTRL imperative 
macroinstruction, data management disables. these and immediately returns 
control to your program at the normal point. No I/O is Pr noMneg.. 


- If, you. do not specify OPTION=YES, and one of.the foregoing : conditions occurs, the 
file is not opened. Data management branches to your error routine, if you have 
supplied one, or to the normal return point in your program if you have not. You will 
not be able to perform further processing on the file. 


peywole Para meter ORLP:” 


ORLP=YES Bs a : : 
May be specified for eorAbIVed files Reentry in eisriae mode; UHSR: you are 
uSIng a card re2e/punch unit with the pepe read station viparure installed. 


In the werlap nied: each GET or - PUT macro processes. a diierent: card. Use this 

- .mode to read a card and then punch data onthe following card: In the: nonoverlap 
mode, you can read and punch the same card. If you issue a GET macroinstruction, 

_ you cause a-card to. be read. If you issue a GET macro and then a PUT macro, you 
punch data. on the same card that was read by the GET macro. In either mode of 

_ operation, you can issue a series of GET macros or a.series of PUT. macros. Five 

_. successive. GEFs macros read five cards; five successive: PUT macros punch five cards. 


2 ‘Three neeaitile Soribi hate for Heeling: GET and PUT. macroinstructions are: 


1. Alternating GET and PUT macroinstructions, when used. with alternating 
prepunched and blank cards, produce valid results if overlap is specified. Each 
GET macroinstruction applies to prepunched input data cards,.and each PUT 
macroinstruction applies to punching data into a blank card. 


2. Multiple GET macroinstructions between single PUT macroinstructions, when 
used with multiple prepunched cards between single blank cards, produce valid 
results if, in every case, the number of GET macroinstructions corresponds to the 
number of prepunched cards between. each. of the blanks that the PUT 
macroinstructions reference. 
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3. Multiple GET and multiple PUT macroinstructions, when uséd with multiple 
prepunched cards between multiple blanks, produce valid results if the number 
of GET macroinstructions and PUT macroinstructions and the number of 
prepunched and blank cards are consistent through the program. — 


Keyword Para meter OTBL: 


OTBL=symbol 
Specifies the address of the 256- coree translation table in your program when 
records in an output or combined file are to be translated on output. A 
translation table is required if’ the keyword parameter MODE=TRANS is 
specified. . . na 


neywole Parameter OUBLKSZ: 
~OUBLKSZ=n —_ ve gases 
Specifies the canah (in bytes) of the secondary I/O area (lIOAREA2) for a 
combined file. lf OUBLKSZ is omitted, the size of the eutput block i: is assumed to. 
be the same length as BLKSIZE. ad 


Keyword Pad meter RECFORM: 





RECFORM= ee 2 see St — Aa ot (9 wi 
locked records are assumed by the. logical |OCS when this 
/. keyword parameter is omitted. For input or combined files, this option 
oe (RECFORM=FIXUNB) must be used. ~~ : 3 po 





RECFORM=UNDEF a 
Used for undefined records in output files only. You must specify the RECSIZE 
keyword parameter when this option is used. If the 8413 diskette is used, this 
septate specification causes ne generavon or an invalid DTF field message: 
_DM61. 


-RECFORM=VARUNB- | w iatclaee oe anol 
Used for variable-length, unblocked records in output files only. 


Keyword Parameter RECSIZE: 


RECSIZE=(r) 
Specified for output files with undefined record format; (r) indicates the number 
(2 through 12) of the general register that holds the length of the output record. 
The record size must be entered into the general register before the PUT 
macroinstruction is issued. If SAVAREA is specified, register 13 may be used for 
RECSIZE. 


RECSIZE=n 
Specifies the record size in bytes used in conjunction with the BLKSIZE 
parameter value. Data management uses both values to invoke multi-sector |/O 
operations in processing diskette files. 
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Keyword Parameter SAVAREA:  . 


SAVAREA=symbol _ : ag 
Specifies the label of a 72- -byte register save area, ‘aligned ona full-word 
boundary. 


Specified for each card file defined for a program. Only o one user r register s save | 
area is needed for each program. 


If you. have a program written for the SPERRY UNIVAC 9200/9300 Series, in which 
register 13 is employed, it may be converted to. OS/3 specifications by adding a 72- 
byte labeled save area (aligned on a full-word boundary) and by _ specifying the 
SAVAREA keyword parameter. Refer to 1.4 for the content of this area. 


If SAVAREA is not specified, register 13 must be loaded with the address of a 72- byte 
register Save area, ee on a full-word monneey) before any imperative macros are 
issued. . 


Keyword Parameter STUB: 


This keyword parameter is used with 0716, 0717, and 0719 card readers: and must 
be supplied when the stub card read feature is to be used. If the 8413 diskette is 
used, both the STUB=51 and STUB=66 a iia are gee 


STUB= 51. | a By 
The stub card read feature applies to cards with 51 columns. wie 


STUB=66 5 23 
The stub card read feature applies to cards with 66 columns. | . 


_ The block size specified (BLKSIZE=n) must be less than or equal to the number of 

~ columns in the card; however, because of the requirement for an even number of 
bytes in the length of the I/O buffer, you must reserve 52 bytes for the buffer in 
defining it with a DC or DS statement in your program when you are Feading, all 
columns of a 51-column. stub card. . fs 


If omitted, standard 80-column cards are assumed. 


Keyword Parameter TYPEFLE: 





Describes an input file only. This option, is assumed if this keyword parameter is 
- ‘not ‘specified. 
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TYPEFLE=OUTPUT 
Describes an output file only. 


TYPEFLE=CMBND 
Describes the combined file when both the read and punch features are to be 
used. 


‘Keyword Parameter WORKA: 

WORKA=YES : 
Specified if |/O records are to be processed in a work area rather than in the /0 
area.. The address of the current work area must be specified with each GET or 
PUT macroinstruction. If this keyword parameter is specified, the keyword 
parameter IOREG must not be specified. 

The following are examples of coding the DTFCD macroinstruction. 


Examples: 


LABEL _ AOPERATIONA OPERAND 


LA 
iD 
oe 

J 
a 
11 Ws 
7 
oe f 
(iu 
‘2 
ir 

© 
Z 

| 

> 
be 

J 

m 


sie eeandl 

RDI precio, bat AL =ARIEAI 
ele eee! Bibi Si =0,0 ae et 
ii LeoeappRe asin 
5 eral ee eRe 
i | ype eer POT ial 
Ti | WorKAlenV EA 


ULE DIEFRINITION -ISAMPLI 


Ho 


Oy 


REAL =AR A | 


RE WZ ARIEAZ 5 1111 | 


. fr, = r ls 
{| > : “ » 
1 J ; 
t ; 
a ; 


IOREGI= C5 

B 3. LIZE RH B80 

E 0 IRM =ONDE.F, 1 
RE B=Ci 

Y PLE FIL E= PUT 

MO D.E.=|S TD 


CN SS a OP OTS HR 
7 
. TI 
. O 
g 


a 
x 
4 
a 
. 
Xx 
4 
| 


Ea eae a (Ee De ee eee 
J 


E SROR = Ex IT 
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Table 3—1. Summary of Keyword Parameters for the DTFCD Macroinstruction (Part. 1 of 2) 






















Remarks 


Specification 


Cmbnd 


an oe 












Specifies processing in ASCII; if used, 
MODE=STD must be specified 














Skip cards containing validity check errors. 


The maximum block size. in bytes 


BLKSIZE** 
‘CONTROL* 


| CRDERR* : RETRY me 


Specified if CNTRL macro is to be issued to file 














For used, 


CONTROL must not be specified 


=a End-of-file routine for input and combined files 


card punch error recovery; if 


He 


Address of the user's unrecoverable error 
routine 


Address of input/output area; output area for a 
combined file | 


Address of alternate input/output 2 area; quips 
area for. ‘a.combined file. ~~ i 





General register (2-13) ‘that contains the 
address of the current record when processing 
in two 1/O areas. Omit WORKA=YES. Must not 
‘ . be used for a.combined file. — 


. Address of input translate table; required when 
MODE=TRANS is epsctice 


Specifies cards are to- be read or ‘punched in 
column binary 








“Specifies records are to be Tead or written in 
compresed code 


Specifies records are to be read and written in 
EBCDIC 


‘For records to be toad ¢ or written in EBCDIC aad 
translated by the table specified in the ITBL or 
OTBL entry, respectively , 


opp 
i ie OSE 
al RL 

| _For fixed-length recor 



















. Specifies that a combined file is to be processed 
‘in an overlap ‘mode 7 










Address of output translate table: required when 
MODE=TRANS is specified 









Specifies the length of IOAREA2 for a. combined 
file . 






RECFORM** 


| vaRUNB | For variable-length records 


rm 
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Table 3—1. Summary of Keyword Parameters for the DTFCD Macroinstruction {Part 2 of 2) 


Keyword ificati Remarks 
RECSIZEt+ For undefined records; general register ae 2): 
contains record size ieee 


_ Specifies record size in bytes. and is used with 
BLKSIZE: for multi- sector 1/O on diskette. 7 


oe ; Specifies 72-byte register save area 
~ "Stub card read for.51-column cards 


Stub card read for 66-column cards _ 


FAP Ose 


TYPEFLE’ |. = rs or 61) For input files’ 


“For output files, : 
poricempines read/punch: file> 


Records are to ‘be a eecsed in Panic: area. Omit 





lIOREG 
LEGEND: 
R Required 
. X~ ~ Optional - F <: = 
f~ bs One option required ; 2 ata 


*Not appliable for diskette files 
**Parameter may be changed on Dp es control statement. 
+Parameter may be changed on DD job control statement a8 diskette only. 


3.4. IMPERATIVE MACROINSTRUCTIONS 


2% 


There are five imperative macroinstructions available to you for processing punched sara 


SAM ules) 
oMlacioineructai: oe Use... cat | en | : : 2, re ‘Sy ai 
OPEN File control | 
GET Record processing eee 
PUT : =... -.. . Record processing - ~ .., . SFR aS ig BARRY 
CNTRL Output and combined file acer sential 
CLOSE File control 


The following paragraphs provide you with a _ detailed description of these 
macroinstructions, and~ provide~ coding ° examples with explanations, when fequited, to 
Sore use. a: : 


UP-8068 Rev..4 | SPERRY UNIVAC OS/3 © . 314°" 
BASIC DATA MANAGEMENT 


OPEN os Oe hae tr > 


3.4.1. _ Open a Card SAM File (OPEN) . 


Function: 


Before a file can be accessed by the logical IOCS, you must issue an OPEN. 
macroinstruction. The transient routine called by the OPEN macroinstruction performs | 
certain validation checks and initiates file processing. A check is made to determine. 
that you have. supplied.all the necessary keyword parameters defining the file. The 


device allocation performed by the job control program is determined. 


- The actions performed by the OPEN transient routine depend on whether the file you 


are dealing with is an input or an output file. For input files, the first data record is 
not available to you until a GET macroinstruction is issued. For output files, no data is 
written; however, the data area is made available for use. Only one file per card 
reader should be- open at “any one time during execution, of a program. 


Format: 








LABEL A OPERATION A OPERAND 








filename-1[,...,filename-n]) ete 
‘0 tee ae oe 
1 


Positional Parameter 1: 
“filenarne oe 

Is the label of the corresponding DTF macroinstruction in the program. ‘The file 
name may have a maximum of seven characters; the maximum numberof file 
names is 16. 

(1) or 1 fe | 
Indicates that deletes 1 has been preloaded with the address of the declarative 
macroinstruction. .. °°" | ana : 3 


Be ay ‘os 


Example: 
| tABEL ial AOPERATIONA —  OPERANDD a a 
16 


1 PeagE POUT), OUTPUT, UTIs TL 


Enters the transient routines necessary to prepare the DTF macroinstructions whose 
labels are INPUT, OUTPUT, and LISTING. Checks that they are prepared to access 
these files with the next imperative macroinstruction (GET, PUT, etc.). 
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3:4.3. Output a Record (PUT) 


Function: 
The PUT macroinstruction delivers an output record to me bess locs in either me 
output area or a work’ area specified by you. >. i : 


Data management delivers the records singly to your output peripheral device. A 
general register (2 through 13) must be supplied (by means of the IOREG keyword 
parameter) when a standby area (IOAREA2) is specified and when no work area is 

_ used. This register provides the logical |OCS With a place to put the address of the 
current output area. Records processed in an |/O area can be referenced directly by 
means of the name you“have given to that area (IOAREA1). The output areas are not 
cleared after the current output data is sent to the device. You should exércise'care to 
clear the area before use or to supply records, including blanks, which completely fill 
the output area to the logical lIOCS to prevent spurious characters. from appearing. in. 
the data. 


When records are processed in a work area, the logical IOCS moves the record into 
= the I/O area. This frees the work area for Veursupeeduent: PIQcEssiInge: 


| ; When punching a Tecard containing an odd number ‘ot characters, data imaneuoment 
places a nonpunching_ character in the VO area at the very end of. the data you 
supplied. 


Format: 









~ OPERAND- 


filename , (workarea 
(1) (0) 
1 0 


AOPERATIONA © | 











Positional Parameter 1: 


filename 
Is the label of the corresponding DTF macroinstruction in the program. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the declarative 
macroinstruction. 


Positional Parameter 2: 


workarea 
Is the label of the work area from which the record may be obtained. 
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(0) or O ( a 
Indicates that register O has been preloaded with the address of the work area. - 


If omitted, indicates you have chosen processing either by means of a register (IOREG 


keyword parameter) or by directly accessing the data relative to the name of the I/O 
area. 


NOTE: 


When the work area is specified, the keyword parameter WORKA=YES must be present in 
the DIF statement. 


Example: 


© 


. “LABEL AOPERATIONA | eos etree en aoe 
“is Trax The 0, AUT WERIK 


Progiaminifig Considerations: 





mee ar tet 


= Variable-Length, Unblocked Records 


You must determine the size of the output record and must insert the size at the 
f 
beginning of the record before issuing the PUT macroinstruction. Record size includes ( 


the 4- -byte record length field. ‘You may not access the first four bytes, which are 
- reserved for block size. — 2. 


m Undefined Output Records 


RECSIZE=(r) must be specified; you must determine and place the record size in this 
register before issuing.each PUT macroinstruction. 
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CNTRL 


3.4.4. Controlling Stacker Selection on the Card Punch (CNTRL) 
Function: 


‘The CNTRL macroinstruction allows you to control ‘stacker. seléstion on the 0604 card 

punch for output or combined files. In processing a combined - file, you may read a 
card, process the data read from a card, and then select an output stacker ‘in 
accordance with the data‘on the same card. If you issue the CNTRL imperative macro 
in your: program, you must specify the eos keyword parameter, in: the DTFCD 
declarative macro (3.3). ‘ 


The CNTRL macro is ignored if you issue it to a card file processed on the 0605 card 
punch because its small error stacker is not designed for selecting cards. 


Format: 








AOPERATIONA OPERAND Apion’ 


filename ) ,SS|(,1 
(1) 
1 , 


LABEL — 









Positional Parameter 1: 


filename : wee 
Is the label of ‘ie DTFCD declarative macro defining ihtee output or combined file. 


a or 1 
Indicates that -you have..preloaded register 1. with the address of the DTFCD 
declarative macro. 


- Positional Parameter 2: 


Specifies stacker selection on the 0604 card punch. 


Positional Parameter 3:50 ee a SRE Ee weet Pe aS tae 


Specifies selection of the normal stacker. 





oon Specifies selection of the select (error) stacker. If ine ‘third soshional parameter is 
omitted, specification of the select stacker is assumed: If the third positional 
parameter is specified, but is not specified as 7 or 2, specification of the normal 
stacker is asSumed; an error flag appears in your program listing. 
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«3.4.4.1. Using the CNTRL Imperative Macro 


You issue the CNTRL macro after any PUT or GET imperative macro that punches or reads 
the card you want to select, and before any PUT or GET macro that processes the 
following card. If you issue several .CNTRL.macros. in succession, the-last one you issue 
controls which hopper the card goes into the next time card motion occurs. 


A look at the following schematic diagram of card flow through the 0604 card punch may 
be helpful. in visualizing what-the CNTRL macro does for you. In Figure 3—1, a card moves 
from left to right,.from. the input hopper, past the optional prepunch read station, to the 
punch station: It then passes into one of the two output hoppers: either the. normal stacker 
or the select stacker, according to the position of the deflector. The 0604 card punch 
subsystem, itself automatically.deflects error cards into the select stacker; it.is the deflector 
that can be controlled by the CNTRL macros issued in your program. 





PUNCH 
STATION 
7 DEFLECTOR 
INPUT ) TA 
HOPPER - . 
PREPUNCH POSTPUNCH 
READ READ 





STATION STATION 


SELECT NORMAL 
STACKER STACKER 


. Figure 3—1. Schematic Diagram of Card Flow: through 0604 Card Punch : 


The normal sequence is that a card in the postpunch station passes into the: normal 
stacker when the following card enters the punch station; if you have set the deflector by 
issuing the CNTRL macro, however, it passes into the select stacker when the card 
following it moves (is fed or punched). Stacker. selection. for a card that has gone through 
the punch station thus takes effect when a macro is executed that moves the following 
card — a GET or PUT macro, depending on file type and your processing. ,. 


When a card file is opened, then, cards passing the pee station are sent to the normal 
Output stacker until you issue: ior Rs a8 ag 


a CNTRL filename,SS; or 


=  CNTRL filename,SS,2. .-- 


ern, 
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Then, the following imperative macro (GET or PUT). that causes card motion results in one 
card being placed in the select stacker. If you do not issue any further CNTRL macros, 
cards following the card that went into the select stacker are sent into the normal stacker. 
Thus, a CNTRL macro to send a card to the select stacker applies only to one card: To send 
10 cards to the select stacker, you must issue 10 CNTRL macros, properly interleaved with 
PUT or GET macros. Note that the CNTRL macro causes no card motion itself. 


For an output file, each PUT macro causes a card to be fed into the 0604 card sunch and 
a card to be directed into an output hopper. You: must issue the CNTRL: macro after the 
PUT macro:that punches the card you want selected and before your next PUT macro. 





Example: 

a “LABEL _ AOPERATIONA ~-OPERAND is, ss aaglin elec 

: 1-0 = 4 10° = 4G : a ; ee i ok 

me ee eerie ci me eee 

2{....1.,| Pur. . | PUNCH 
fooii ti. |ICNTRL PUNCH 

UE seated eae PUNCH meade eae nee tana eeae 
Peo ti LCNTRI PUNCH SS.,.20 00 ceiiides gen dia 
eed Fence Ane Ce a ee ot 
Freee one 1 Pees EF Hitseee een eeeeeeeees 


oh 


Punches card 1. 
leet puliches card 2; cane a ‘is sent, to the normal sti stacker. 
3. Punches acre 3; card 2 is sent to the sche stacker. 
4. Punches card 4; card 3 is sent to the normal stacker. 
5. Punches card 5; card 4 is sent to the select stacker. 
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6. Punches card 6; card 5 is sent to’ the. normal stacker. 
poe Punches nae 7 cad 6 is:sent to tbe normal s stacker. ~ 
“e 8. On closing the: auiput file, sehid Ti is sent to the normal stacker: 
9. PUNCH is ; the logical file name of the output card file Bain processed. 


When . you are processing. combined files. (TYPEFLE=CMBND), you have two processing 
modes, overlap and nonoverlap. The overlap mode is specified with the ORLP keyword, as 
you recall from 3.3; if you omit the ORLP keyword from the DTF of a combined card file, 
you process the file in the nonoverlap mode. The action of the CNTRL macro is slightly 
cinerea nts in oan TASS mOUES consider the overlap mode first. 

For a esvibified card file with overlap, each GET or PUT macro advances a card, and the 
CNTRL macro: applies’ to the card processed by the previous GET or PUT macro. The 
sequence of instructions in the following coding example processes a combined file deck 
named COMBO, in which each punched card is followed by one blank card. A punched 
card is read, data is processed, and some resulting, data is punched into the blank card 
following it. 


Example: 


LABEL | AOPERATIONA OPERAND = . A 
oe ig Jog OEE 


ie 


. _ u 





Cc ) ME X), = i r . 


tba 
LA 


K ts tT C3 o 
e Cy Wa E> (J 
e 
oxy i 
: \ 


(za ER EFA ee FR SRE OR Ca DS FW 
re : Cy , 
beni 
ev 
© 


we 
A) 
— 


mM Cc 
Cy CX 
b> CJ 
ejljeer) | 
VS. 
Px] m 
iT) e 
t oO 
an: 
pF 


| 


a 
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The instruction sequence shown causes all the prepunched cards to be sent to the 
select stacker and all of the newly punched cards to be sent to the normal stacker. 
Processing continues until an end-of-data (/*) card is detected (2.3.2); at this point, 
the end-of-file routine ENDFL closes the mee and ane 190. terminates. 


On the other hand, consider the nonoverlap mode of processing. a combined. card file: 
A single card may be processed by a GET and a PUT macro. A CNTRL macro ‘may be 
issued after any macro that processes a card. If a card is processed by both a GET 

and a PUT macro, CNTRL :may be issued after;either the:'GET or:the PUT. macro to 
control. stacker selection’:of: that card. If-several CNTRE macros, which ‘apply to a 
single card, are issued, the last CNTRL determines which stacker is selected. 


The following coding example reads three cards from a combined card file named 
COMBO2, processed in nonoverlap mode and containing no blank cards. It punches data 
on all three cards; the first is.sent to one Belect eterno and the ether two my caids 2 are ‘Sent 
to the normal stacker. aa 









Example: 
LABEL AOPERATIONA * @PERAND : A 
| 10 16 
ower see temo a. 
Pope 2 
ae fs a | Pur.. tL er bie paella let 
Pei tis | CNTR! COMBDZ,.SS 
Pei tii | GET... | COMBOZ 
Pei ti, | GET. | COMBA 
Pv tii | PUT. . | ICDMBS2 i" 
Fioiiiii| CLOSE! COMBS are: 
ce eee fi pale nest til 
veeny ses | FE : 
eewaes 2 eng 
BO DD DO ILYP 
faethe ce 
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CLOSE > 


3. = 5. 1088 a | Card SAM File (ctose) 


Function: 
The: CLOSE macroinstruction initiates the termination procedures for your card SAM 
file. When all the data i in a 1 file has eee iiascvasintl a CLOSE macroinstruction should 
be issued. » 2) 8 0). RGN ata , 


Format: .'; 










~~ AOPERATION A. OPERAND 





filename-1[....,filename-n] 


Positional Parameter 1: 


- filename © 


oe 
-_ 
Is the label of the corresponding DTF maeroinstruction in 7 your program. ilanaric WW 
__ may contain,a maximum of seven 1 characters; the maximum number of filenames 
is 16. 


e- 
; 


(1) or 1 


Indicates that register 1 has been preloaded with the address of the declaia ive 
macroinstruction. ; 


"ALL 
Specifies: that all files currently open: in ‘the: jab 4 step are to. oa closed. 
Exaile: 
LABEL TOONS, 


OPERAND 


icoamaTecaad is 


Enters the transient routine which closes the file described in the DTF macroinstruction 
whose label is INPUT. 
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3.5. ERROR ere en eae HANDLING 


3.5.1. FilenameC 


When certain errors or exceptions to file processing performance. are detected by OS/3 
data management, it will:make appropriate entries’in specific fields of the DTF file table, 
which your program may address in order to learn of these conditions and take the proper 
course of action on regaining control. One such field is filenameC, a 1-byte field which 
you may access by concatenating the character C to your 7- character macht filename and 
using the test- under-mask (TM) instruction. . 


Refer to Appendix B for the meaning of the bits in filenameC of the DTFCD file table which 
are set to binary 1 by OS/3 data management for certain error and exception conditions. 


3.5.2. FilenameS 


When you. have sascified CRDERR= RETRY on a card Buneh file DTFCD and six successive 
attempts to punch a card have failed, OS/3 data management sets the hardware error bit 
in filenameC (see Appendix B) and also places the image of the card which is in error in 
tilenameS :of the DTFCD file table. FilenameS, which. you may address in the same way as 
filenameC, is an 8Q-byte field for all modes except the binary (image) mode, and a 160- 
byte field for that mode. FilenameS does not contain the error card image if the file is a 
combined file. Software punch’: retry applies to. ‘the 0604. card punch. Por the 0605 
(integrated) punch, the operator. can Popunen erroneous cards. ‘ 


3.6. SAMPLE PROGRAMS 


The following examples have been ‘constructed to illustrate typical uses of card input, 
output, and combined files in BAL programs. They also provide examples of the OS/3 job 
control statements you: need to ‘implement your prediaine. 


v A8Y 8908-d/N 


[> 


LABEL AOPERATIONA OPERAND COMMENTS : Se = 
6 Me 


itunes ce eemen mesa ee ree ee eee ea Uh tos heed Lina vit de a oy eiarar OF 

| En eas ae Le Sa ee ee as en ata Hap Meee Nee sane {ZR oe Yat re PA es le dott i i iors eee ere 
OB STREAM jTO KEC TE A SEM AUER iL je tas es yanareres OEE Soe een cag es 
is (Ee bomen: Hootie bad i 


OB . IE 


‘Ad 


| 
— 


FE 1 Pe RS I GAR A CR a a GR Dh 


4 ee eee o A. eee L. eee es L att Re JOR (ote 0 ese Wer tae 
ae wi GY L. cadena Ps em ae eae I. _L 


SN 


en ee 


rh 
S 
J 





oo a 


NPT, | 





PLE D BUSE, OF A DATS MANAGE on “CARD I PUT, FILE: oan 


Z DYER REGISTER uae meds ime 
irae Be nal et LAs ease LET ate 2 : Tes er Ee Vey : 
i ViE_AREA ADDR TD R13. Pare ee Ri: pire i es serie ee | 
ak, D, e FILE, TM de ae elk ete Fils ia We bas Bae 











er tH 
U 


Hie 


“TINaWaOvNWIN Viva oIsva 
€/SO_ OVAINN: AddadS 











1. .§ WORK i 
ae eae tae ee (ee er eee a rae Seer ees | 
| PROC DATA, IR a MF fs \ Pepi at ae - Feet ee Fa ns eo Uap | 
icine caprere a poe we ae 4 Ree Peron a i rare: Fish Lae 425, a 
Bee aera! ww wae te sie we Poe a) een we a Fore oe eee ae es eee es 






= E iE, CLDSE CARD. FILE. a l 
af END_OF J8B 1 
on Sr ier Hence SN ae (WA es os LAN Oe 


bettie cde (tt EVO vert Oat al ORE a Gm 
{ \ | ~ 4 ¢ ; ; 





be dt NS a fe fateh 3 





‘ay ‘ Cc) Cx) 
& mM € S = 
J 
|Z hy 


CO 
IC 


~ OC-E 


( } f i i 7 
2 : Ke 
LABEL AOPERATIONA , OPERAND _ ; COMMENTS 

10 | 16 













if NLC IOUBO tos oo on DATASERUNGATED: IBLT, | SET, ?. iP ca as 1° Pace Dalya 3 
Mh ot ti BRANCH, LE SET BACK INTO. PROGRAM |i... 
se Soe CONTINUE, PRB CESS ING bt ache do ab gaat 

OTHERWISE: CANCEL, PROGRAM ba cle. ridin at 





_ id ] 
ARE iret ad on ene ee rie CLS is ae ent es Bl ele aL a a a 
Soe ee hg ey i ge a a eat Looper birar id dpoaoada i dite 

REGISTER SAVE AREA . |. pt ee td a gat se ar 
BO, 1 set AREAL titi fe Nhs he 9 att ota 
BOs Liss MORK, ARES cietee vEERS , 
Re eas tO A FO WR me ns CRY Wea Ves a EE TDS WOT SC EN is SAN ew et WD el eB OS 
{CA RID, .DM STEM ae (es WS ae Os i es ie ed lt 
or a oe ee eee ene mr a emer ery ae Spege dpe get aa) aa Is, 


BLK SI E=60), 5D ADDR-EDE, £RODR- ERR, TBAREA Le IOl, »MBDEsISTDy 


TYPE Fits = INPUT. WOR A. 
INET : TE SAETEPEN SSE STEPTPORITIETIT | 
e ek 


wie 
C yp |. 
al oe ix 


< 
m 


wv we .. 


$5 (aa SPR Sa A ER © Ne ay Cem Fe Bw 1 
x : ope. 2 ©, - ‘&, ox 
nae ig OH 

fobs i 


AN 


" 


eat rl We Wl 2 ae se ees De aU a) oa 


JOB STREAM TD_EXECUTE LINKAGE EDITOR Seah Aca ge At Ae eid 





—- 





: Tif CEOeANI pence oe ASSIGNMENT. DE CARD READER». 
| } fiche Nike a Do ke ee Boe Pa a ey he OR, De ate a ee te ae gece Fede reac ie ra 
id )} STREAM TO EXECUTE : PROGRAM eG oe a rae ee am ws ee ee ae es OP a vs 
} Bevin ba2 i ioe oa aera dy pt Ee inn pe ia. pc Ye or E aiek bt a aE } 
i | ee Pci e B  y ao ees a ae ee ee ee ! 4 i! 








sie Wal eres oe ee oe aN a ot ae a a a Sh ie ie pata 7 


“A284 8908-dN 


ae 


~ LNAWADVNVW VLG oISva 


A 


--€/SO DVAINN AYYSdS 


‘Lt-€ 


3-28 


tore ¥ 


SPERRY UNIVAC OS/3 
_ BASIC DATA MANAGEMENT 


UP-8068 Rev. 4 


: . T Sa Oa a a T = 
prrri ce 


T rr ae ae a ioe 


, C3 
m . T T T | T T 


porwr gy 3 La 


4 2 
‘sees’ 






4 | H . 3 1 H # > i ! Hl : i 3 : $ H i a ‘ ‘ : t if 4 ! Hf a 4 i ' 1 é i + hi | 






PTC foe PTO A pI aS st mr 7 ee ee pe od Se ESP op ek et 






Ler Prenat? + Lee" es ep oye ee peepee op spesperap er Sea oe 
La ae ca (ey es er eg | ‘ eS ee a 






Por Ty | Pep tT PT an ea ae ae ae Rae eT por cs i Os Sa Saar A Fa ape re T Bae me ad a a Le amet cot 









Vash TS ES | TOR Ti ae aa Ue cf . TOT ey EMSA ae TT. TOY porn ey. ares ne oo ae 5 SLL 





mes (gees wa i? Ce eee ee Mere ren ee i pa ee See pet ii Poe be Seo ba hy 
os eee ee pete tao coe ss es BW Se a a Tory Sa aa ae : 

ee ae Fa Rs eg Os a a as sie aa a Taer Bq ana 7 iad ie as as ae A a 
| ae a ak a a ata ae ao ee Cavs SsQv "san TS Ju i et es a in Wa a a 
oe S30Q4ad LvSdzad QN SAT!” | 
i A a a mhe=) ‘ss Gadi Vv’ iva svt ne a *7 9 & C , ae . 


pe ae sae Se as Se ea 
































4 Pane 
: a : 
BRE Ee ee ie ae ae Sa De Sle 









TT mrp i rn “gry Tras io) 7 | 
TT | ae hoa oe ou] FQ vOdy veaV SAVE 89a i ee a oe ea SE ET 
os en 1 = owas ; aan es TT TT a 2 ae a Se a a a ra an 8 Ty Sort wpe ea ee ae 
Seascale} WSLS LOTT WING ove RN RA Ce ne ee 














cn na 0 TT 





Hr osqre ineglaq svar 1 SS SHE 
Se a a a a Wa T a 0 ae Speer | 
Coe eer ae ae ee oe ee en ee a a ed ee 


ie ile ries T oe is Ue yp ey 




















: aed iaas 


“TOTO TT por y ; T Tr Tr pre ; oa A Tl, rr Tol Tw: ad SINDS xo GL WWESIS- eer 


if YT wT J I TT | se ae ae | ie ee a i in qT ee ee ee Ls a ee ee a Sa Tek atest s eee ee ea ae ar eal oe bor ars as oa 








my yo J ay 1 ] LATTE ] LS PT ee cae ae it Sai Glas ace Ppl ana ry tT ee Cae Wi eee a in ea a a ee oT et aed? or 


SLNASWAWOD aNnvHadO 





3-29 


SPERRY UNIVAC OS/3 
BASIC DATA MANAGEMENT 


UP-8068 Rev. 4 


I-17 ?T 7 OT rr ae oe an eee i a a a 
i 


i 


rH 


ied (er es es Se 


fae ey i ade 


[ET ob ot ee ae | 


| Fae ae O Sa a [> rr Totals ee lee ee aes eo i So era a ee ea a es cet ae er ae 


fae ie a Gia (eae ak ill ee We a i a ae eae We Ca Ey oT ee 


TTP TAN FOQIS SLAVS GL 





$ aaa SSE ei ae COS PS en eh VOR Ear see Zale ace Cie ee ee H 


oT OyQITas SSVy 


ee a ae eee Pan eae (ane ieee iy a, Neeser e eh Heche ak eee ay ’ 


S fe ae iSS'N= 
Kha aah 
is 


se he ie (ie Se an Nas an als ae es ak Pld PVs) N bt 


S=5 a Sd Qw eS 


ie i i TTT 


VAS! an annix IS=WO Q@so38" “Ry geSeaIOTy “Nd iN@="37To 


VAI=2VIIVQI WaT" Vaev@T ‘as =sqaTsOg=: SZTSIT 


ie al a a eg rer 


ae “Ty i Se Sees Te Ma ae ee ee Ger cae tT SL | 





oe pe ary ee aE ySSy G/T 0 aed eae a can sh ae 2 eB 


i] T YT Lie i fn DP 


i a Fie a Pf op ae ae Te ee i) ee Se Ree Se 


| Torr | | acs eaees (aa fae 


| eee ae a 


{Oa eos ia i (ae 





[2 Pe err 7 coe mn ar ch ia Oa se ae ee ee a ae dB 


| ae “TT Wyao@ad TBDNV>D TT TT TTT is re a ie a oa a a ee 


SLN3WWOD QNVH4ad0 


3-5U 


SPERRY UNIVAC US/3 
BASIC DATA MANAGEMENT 


UP-8068 Rev. 4 





en 
iis 3k 
= 
on 


| ee ee (a 


Ge sae oa eo Oe T 7 | ’ 

: i oe ef i rE { | Sie ae He | Lee ee fee T io ieee Dene aaa 9 aL EE Pay. i pine eee Min a i ; 

ae oon eee | | bod | Eb i ee ie: ; wt Ln x ae as ae ae Oa TY oe KY 
tora | bor if [ oe a | | a ne ae | | a ee sae { pees casas aan Oa T to pes TT Te SSE T TTT ep rea i as a as eee ie ea RO a “TST Te 

| ee Aree ae Se : | | i os AG yds “45, ry aan ae Gi ed T. bee ae =f a fae ee ee ae Torr t Tv i: ae ae ee ats | ear io oe T tie ie er a an a 





fey ane Sa e vauv @/T “SINT WIVO-H ONT SavdsId 


| 2 ea ois eae ] i ee aman Toe TT TB Oe T see nee Oe ee ee ee ee } ne ee i ae ee ee ee ee 


y fi spook T Say ehh UF Le cee ton ti a va8Y ‘Q/T@INT 


a 

V1 SNTEWAO STS dave Nada TT IT oT OWED 
ve 
| 


SITS dSNTEWGS TEV \ 


pop oY oT ror fet as a Siar i i ee Cree i as a a as a a a 


a ae a 


ee a es a a Page prspapr 


Pal TUTTE Ca Dey (ieee ans lier ae i Pel, alana l- ca ima cali SN fi 


se a el Ss A (a a la ad A ee 


11 FONE BW Tea A 


fares ce a tee ie aa aaa a Ca a i + ‘Te Toy wy wr pe eae ae 5 aa eran al 
+ A t t 





Pee ws tae Ty TT 





pos me jo 


| ae fae fa Oi Tot ae Ty T TT dav 7 i WdvVaqy Ete deh oy Toe Pals! A] WN 


fc) 


ELT T RS: (a OR a RE Cp 5 


‘ne: ae os ae a Try Rar faa (a TTT? 1 orm es PoP ieee ae i es (an a a h x 
Tt fa Tt TT soUSTOSS WING “av a To Peete TT ee oy ae 0) 





t 204 f QroT oY bie (ae ea es rp st | ee fr a a eG a a ee Ys, a 


TY {Tete pe EEE La os ies ae PEPE pe nop Bee a Ty at reno Ts 








SLNAWWOD V ONVH3ad0 





Ny 


/ ; 
\ | 
LABEL 


AOPERATIONA 







OPERAND 


oT ae Ba es ae Poo la 


bs a i dosed) Peed a Poet 


toa wedhaah ok, Dedicegs & Al coe eee Pay hy I/O AREA 


Boke ee, Poot Ea eae: bee TY REGISTER SAV 


COMMENTS 


$ 
* i bow. ob 4 4 od 


ttt ody i ae CANCEL PROGRAM | 


3 Lae aetieteck | rie 


' 


sle_CARD ba SYSTEM ate ee Oe eS be ee 


Peele eer? Seem Saal ae 









j ; 


E AREA... 


a oe ee 


incl ate ats aie tele My Camseeals es eyed cts iT / 2. AREA, ic 


! ° 
bo. oe toe : a 


1} DARE AZ DIDAZ, MOL Bez as DPT LON ore N Ye. S, DUBE ‘s Ks ze 80, 


TYPEFLE=CMBND,SAVAREA=SAVE 
COMBI. - its ; fist Sisvae de: ois saree te <6 H bo) aX, Heo te oe 


. DB STREAM 7b EXECUTE LINKAGE €DIT 


| a 


FD. COMBINE. 


a wo Sr 1 TO = cei PROG RAM . 
Bbc ce als. Ste hte acne i him hE? ot kB eee Tee on a ag 
Og 





by A8Y 8908-dN 


LNSWS9VNVW ViVd OISVd 
€/SO OVAINN AY¥YsdS 


LE-€ 




















‘ 



























































ee fag. &. 2g BM pee te 
3. Ste” dea dh HE : 
: > . : i 8 
> wig . 
me at ° 
Sh), . . i £2 * : Fi a 
fi : on . py : a, be, 
‘ 
ee : 
pe nnd 
. x a of 
_ ra 7. BAL es 
ona ie a a. SE y . 
, : 




















UP-8068 Rev. 4 SPERRY UNIVAC OS/3° ” 4-1 
BASIC DATA MANAGEMENT ¢ - 


4. Diskette Formats and 
File Conventions 


4.1. GENERAL 


This section describes the data formats and file conventions that apply to the 8413 
diskette subsystems files supported by OS/3. The 8413 diskette is a rapid replacement 
medium for card processing devices and provides multifile volume and multivolume file 
exchange capabilities. 


4.2. FILE ORGANIZATION 


The 8413 diskette is a single-sided, fixed-sector storage medium used for sequential file 
processing as a substitute for punched card equipment. The diskette subsystem handles 
single or multivolume input, output and combined files. A maximum of 19 files is allowed on 
a single diskette volume. A summary of the 8413 diskette volume ehavacielstts follows: 


Tracks 7 (0-76) 

Tracks (usable) ne P73 73) 
Sectors per track 26 

Sectors (records) per volume 1898 

Sector size 128 bytes 

Files per volume 19 maximum 

Number of volumes 152 maximum per file 


Figure 4—1 illustrates the track and sector organization of an 8413 diskette volume. 
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Figure 4—1. Typical Organization of a Diskette Volume 
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File description labels are written on the first track (track O) of each-volume of a diskette 
DTFCD file by data management. The maximum number of mes that can be written to a 
vores! is 19. ne ape cas moytS: Uskeule file kabel: format is: oe 


O label ID 





4 
LABEL alas 
76 
81 
NOT USED 
124 
NOTE: | 


Details on the diskette file description label are presented in D.5. 


4.2.1. Diskette Input Files 


Diskette files can be contained on.one volume or can span several.volumes (multivolume. 
file). Information on a, diskette volume is organized into two. areas; the index track (track QO). 
and the data files, (tracks 1 through 73), Track 74 is. Not. -used; tracks 75 and 76. are 
alternates or spares (See Figure 4—1). - © ss SG pala he oc oY ene 


The index track (track 0) contains a volume label (VOL1) in sector 7. Sectors 8 through 26 | 
are used for the file description labels. One file can be. described. in each sector; therefore, .a 
maximum of 19 file description labels can be entered in the track index. : 


The.data portion of the diskette files contain punch card.images (EBCDIC) with one record to 


each diskette. sector. Each sector is 128 bytes long, and any unused space. in the sector after 
the record is hardware padded. 


All diskette input files are read-only sequential files. Multivolume files require that the 
volumes be mounted in the proper sequence, standard mount messages previee prompting. 
to ensure that the volumes are mounted in the correct order. ve 
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4.2.2. Disnerte dad a Files 


Diskette Sntsuit files are rand white ‘seauacual files allocated’ on a: sector basis. All files 
must reside in a contiguous area. When the file description label is written, it includes a 
pointer to the beginning of the file. Card images that are read to diskette are entered 
sequentially, one record (card image) per sector;-unused space -after the record in each 
sector is padded with binary zeros. 


4.2.3. Combined Files 


Diskette combined files are read/write files that are used mainly for updating records. A 
record is read, updated, and then written back into its original location; this is the 
nonoverlap mode of processing. You should exercise extreme care when using combined 
files, because destruction of the initial contents of the record read may result when writing 
back into that location. The overlap mode of processing for combined files is not Supported. 


4.3. RECORD FORMATS 


Diskette records fall into two categories: fixed-length unblocked records and variable-length 
unblocked records. Records are contained one to a sector within a file. There is no record 
blocking of diskette records. 


4.3.1. Fixed- eenge nECOree: | ( 


Fixed- ieauth disieeite esborae are vail of sais ieaati a a given file. Diskette records are 
generally the length for a given card type image (51, 66, 80, or 96); however, the records 
can be any length from 1 to ee pyres: Figure 4—2 illustrates the el length igor 
characteristics. 


4.3.2. Variable-Length Records 


When you use variable-length records, data management preempts the first four bytes of 
every block (in this case, record) for use as a record descriptor word (Figure 4—2). Data | 
management calculates the length of the record and inserts this for you | in we aitst two 
bytes; the other two bytes are used by data management. 


Data management, again reserves the final two bytes of the record descriptor word (RDW) 
for its own use, but the first two bytes must contain the length of the record of which the 
RDW is a part. 


When you spécify that your records are variable and unblocked, data management will write 
out one block for each logical record you submit, regardless of the amount of available space 
remaining in the I/O area. 


You must not use the RECSIZE keyword parameter in your DTF for a file containing variable- 
length records, because data management expects to find the record s size in the first two 
bytes of RDW. 
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LEGEND: 
r Record descriptor word (RDW) 
A Data record length plus padding to fill out the sector 
B Variable record length 
oo C 1/O area layout 
( \ P Padding 
NOTES: 
1. For input files, data management passes to the user the record length and data portion of the record. 
2. BLKSIZE=n specification on DTF macro and file label block length determines the size of record processed during 


OPEN processing. The maximum block size of multisector 1/O is 1024 bytes. 
3. Unused sector space is hardware padded. 


4, Under multisector |/O, user IOAREA contains multiple records in either fixed unblocked or variable unblocked formats. 


Figure 4—2. Diskette File Record Formats 
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_ 5. Function and Operation: 
_of Diskette SAM 


5.1. GENERAL 


This section contains a brief description of the data management modules that apply to 
SAM operation. for input files, output files, and combined files used with diskette operation. — 
Following’ the functional description is’ ‘a .detailed explanation ofthe declarative 
macroinstructions that define ‘the* three types of files. This section ‘concludes with ‘the ' 
INETEUNe, macroinstructions that initiate, renauct: and tevnnate ae sigue ce 


NOTE: a 


The 8413. diskette processor does not handle compressed code translation. 
5.2. FUNCTIONAL DESCRIPTION 


5. = a input mecord paocessing 

Diskette input files, ‘like eanened sar input files 12. 2. Ae use the: aed unblocked reeord 
format (RECFORM=FIXUNB). Diskette records range from a fixed length of 1 to 128 bytes 
per sector... In addition, diskette ADDRES files can: seat in yaa aroplecnes) record ponnay 
pee ee “ % f3 Cathet 27% 

Data management accesses diskette. input. files ‘i in: ‘read. mode: sly, ‘Orice data fanaaenieni =. 
locates a diskette file label at open time, it saves the file.label address and certain fields of . 
information from the label such as file extent boundaries, i.e. beginning of extent (BOE), end 
of data (EOD), .and. end. of extent (EOE).: Data’. management: then :compares file label. - 
information with DTF ‘specifications to determine if: the file should be processed under — 
single-sector or multisector I/O. It'is the user’s Fasponisibility, here to eAproviee: me areas of 
see size to handle the nloek aetgen: mace eee " ‘. dea oe 
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5.2.2. Output Record Processing 


Data management accesses an opened diskette output file in both read and write modes. 
Using the file-id on the job control // LBL statement, data management searches the index 
track to locate the corresponding: ‘file label and saves the file label address to be used at 
close time. Files can .be extended: or overwritten on output only if the expiration date has 
been surpassed or if INIT is specified on the // LFD statement. 


If specified on the // LBL statement for the output file, the new creation date is then 
inserted in the file label; otherwise, the system date is used as the creation date. 


If INIT is specified on the // LFD job control statement for an output file, the file expiration 
date is ignored and the file is overwritten. If EXTEND is specified on the // LFD statement, 
the expiration date is checked and if still valid, the file is extended. If neither INIT or EXTEND. ~ 
is Beaten a normal check of SK enone date occurs. 


If no major file errors secured to that point, data management writes the label Baek; to the : 
index track in its original sector location, positioning occurs if EXTEND mode was specified, — 
and data. anagem soy marks. the. DTF- as opened and. RaSSe< control to tue next instruction. .. 


Data saanaqement writes ocitptit files via the PUT aperauue macro dither by single: -sector 
or multisector |/O (determined by BLKSIZE or RECSIZE DTF specifications). When data - 
management closes output files, it writes all necessary buffers to the diskette to avoid loss 
of user records, and updates the EOD field of, the file label by reading the label, updating it, 
and writing it to its original sector location on the index track. Finally, data management 
resets indicators and fields in the DTF and marks the DTF closed. 


5.2.3. Combined File Record Processing 


Data management handles combined files (files capable of GET/PUT r functions) at open 
time.the same way it: mandles: nPEE files (5. 2.1). PI ys ae 2s | 


kewise: eee ciees: GperatiOne: data imanaaenicnt handles eoinbined files as Outplit files 
(5.2.2) with one exception. If the current EOD is less than the original EOD, i.e., partial 
update occurred, data management does not update the EOD field on the file label. If the 
current EOD is greater than‘the original: EOD, i.e., Tile extension occurred, data: Manegemens 
updates the EOD. field in:the file label. as / 


Data. nandgemant processes GET and: PUT. aiskerts éoerations tor: éonibined files andeE 
single-sector |/O..The IOAREA1 receives the input record via the GET macro. The user must 
move the .record. to. IOAREA2.:and then update it.. The contents of IOAREA1 are 
superimposed on the updated record in IOAREA2.: If an invalid character results, the original 
character in IOAREA1 will be substituted in IOAREA2. From there, the PUT macro writes it 
to the diskette at the sector from which the original record was read. Data management 
repositions back one sector before each write so that the PUT writes directly to the record’s 
original location. When a series of PUT macros occurs, however, no backward sector 
repositioning occurs after the second and all succeeding PUT macros. The user must take 
care in moving updated records to avoid loss of existing data. 


ra ” 
f 
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5:2.4. Multisector 170 


Multisector 1/07 is allowed for the diskene: up to a maximum: VO — count of 1024, This 
means that up to 8 full 128-byte sectors (records) can be read or written with one physical 
1/O. Many more sectors can be handled, if record size is less than 128 bytes. For example, if 
record size is 80, the maximum blocksize that can evenly process multiple sectors is 960 
bytes and the number of sectors accessed in a single physical I/O is 12. 


To process smaller records using multisector I/O, the BLKSIZE and RECSIZE parameters of - 
the DTFCD declarative macro must be specified with the blocksize value being an integral 
multiple of the record size. To determine the actual number of sectors to the processed, 
divide your BLKSIZE length DTF specifications by block length field in the file label (positions: 
23 ee 27 in the file label Sector). 


The result’ must be an integral number of sectors. There is no remainder. Records are in 
blocked format in I/O areas; therefore, to facilitate record by record processing, you must 
specifiy either the IOREG or WORKA parameters on your DTFCD macro. 


In addition, the IOAREA buffer space allocation must be increased to equal the new larger 
blocksize specification in the DTFCD macro and reprogramming and reassembling of 
existing card file programs is necessary to use diskette multisector 170. 


In multisector processing, the initial logical GET brings in a block of sectors and either 
points to a record or moves a record to your work area. When all records from a block of 
sectors have been processed, another physical multisector 1/O occurs and processing 
continues until the file is exhausted and EOD is reached. Control then posees to our end of 

file routine (EOFADDR=symbol). " . 


5.2.5. Specifying 8413 Diskette Use . 
The following. steps are required to use the 8413 diskette: 


= The supervisor which supports the diskette must be generated. See the system 
installation user guide/programmer reference, UP-8074 (current version). 


= The: DSKPRP system utility routine and diskette space management must be applied to 
the diskette to initialize the allocate file space before user program execution. See the 
system service programs (SSP) user guide, UP-8062 (current version). 


= The appropriate job control statements must be provided to enable diskette recognition 
and scheduling. The “7/7 DVC statement specifies logical unit numbers 130, 131, 132, 
or 133 for diskette. The ALT option of this statement allows you to specify multivolume 
processing (using two drives). The // VOL statement supplies the diskette volume 
serial number. On a first run, the 7/7 EXT statement allocates sectors. The // LBL 
statement identifies the file (this name should match positions 5—12 on the file label 
of the diskette). 


UP-8068 Rev.4 SPERRY UNIVAC :0S/3:.-_ 5-4 


aed pele MANAGEMENT _ 





Only the first eight positions of the field are used for the file name. The // LBL. 


statement can also specify the file creation date, and file expiration date. Finally, 


the // LED statement SpeeMIes the name given for the file desofiption (DTFCD).. 


For further detail, see sake job ack user aide: UP-8065 Lien version). 


5.2.6. Diskette Limitations 


The following limitations exist for the 8413 diskette: 


All diskette files are created and retrieved sequentially. 


Data management requires that each diskette file be opened via an OPEN imperative 


macro before accessing the file and closed via a CLOSE macro when file processing is. 


finished. Data en also recognizes a virtual device on an OPEN macro. 


The CNTRL imperative macro is = janoted when issued to a diskette file. 


If an error occurs dune file processing in. output de. and Sontral passes to the- 
user's error routine, the user must close the file. in error to permit data management to. 


update the EOD pointer in the file label. 


: Maxim um block s size > allowable with multisector 0 i is 51024 iiss and file processing is 


limited to tracks 1 through 73. 


“Within the same job step, se _ logical fils 1DTE) may-Acoess.a WieKeHe volume:. 


Data management cannot process, in a normal GET/PUT sequence, combined files that 


contain logically deleted data records containing.‘D’ in the first position of the record. 


Data management PUT operations do not. use multisector processing if spooling out. - 


The Output writer Ever this feature. 


All data management mount messages | are suppressed ina spool environment. 


If spooling is in operation, a CLOSE macro does not attempt to access the diskette. 


Sea ee 
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. DTFCD 
(Diskette) 


5.3. DEFINE A SAM DISKETTE FILE (DTFCD) 


Function: 


The DTFCD declarative macro used to define punched card files is also used to define 
diskette files (3.3). Except for the undefined record format specification 
(RECFORM=UNDEF) which generates an invalid DTF field message (DM61; see Table 
B—1), if issued for a diskette, the following DTFCD parameter specifications do not 
apply to diskette files and are ignored if specified for diskette files: 

AUE=YES 

_. CONTROL=YES 

CRDERR=RETRY 

MODE=BINARY 

RECFORM=UNDEF 

STUB=51 


The format of the DTFCD macroinstruction as it applies to diskette files follows: 


Format: 


A OPERATION A OPERAND 


[ASCII=YES] 
[,BLKSIZE=n] 
[,EOFADDR=symbol] 
[,ERROR=symbol] 
1IOAREA1=symbol 

[ IOAREA2=symbol] 
[ IOREG= (r)] 
[,1TBL=symbol] 


/MODE= cc. \ 
TRANS 


[,OPTION=YES] 
[,-ORLP=YES] 

{[,OTBL=symbol] 
[ OUBLKSZ=n] 
ieeroenrs { 


filename 








VARUNB tl 
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LABEL A OPERATION A OPERAND — 


DTFCD (cont) [ REcsIZE- ot 
° n 
[,SAVAREA=symbol] _- 


(TYPEFLE= (‘ 
OUTPUT 
CMBND 


[ WORKA=YES] 





Fora complete description and summary of each keyword parameter, refer to 3.3. and Table 
Bi a ee Pe ae 
5.4. IMPERATIVE MACROINSTRUCTIONS 


There are four imperative macroinstructions available to you for processing diskette SAM 
files: 


Macro instruction Use 

OPEN File control 

GET Record processing . 
PUT Record processing Sao € ” 
CLOSE File control _ 7*: oe 


The following paragraphs describe these macroinstructions in detail and provide coding 
examples with explanations. 
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5.4.1. Open a Diskette SAM File (OPEN) 


Function: 


The OPEN macroinstruction is used to open a file for processing. The transient routine 

called. by the OPEN macroinstruction makes certain validation. checks and then 

proceeds to access the diskette file. The OPEN transient routine accesses input and 

combined files in read only mode (5.2.1). It accesses output files in read and write 
_ modes (5.2. 2). 


Format: 







_AOPERATION A OPERAND ~ 





ee [ filename-n] \ | 
(1) | 





Positional Parameter 1: 


filename 
Is the label of the corresponding DTF macroinstruction in the program. The file 
name may have a maximum of seven characters; the maximum number of file 
names is. 16. 7 ; oo 


(1) | 
Indicates that register 1 has been preloaded with the address of the declarative 
macroinstruction. 


Example: 
LABEL oe ON OPERAND~ — A 
16 a pee 
Tn fren Ty FUT ,OUTIP 


Enters the transient routines necessary to prepare the DTF macroinstructions whose 
labels are INPUT and OUTPUT. Checks that they are prepared to access these files with 
the next imperative macroinstruction (GET, PUT, etc.). 
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GET 


5.4.2. Retrieve Next Logical Record (GET) 
Function: 


The GET macroinstruction makes the next logical record in the input diskette file 
available to you. The data is accessible either in an1/O area or in a work area you have 
specified. Data records must: be in fixed unblocked or variable unblocked format i 3). 


If you specify only one /0 area and require ésingle: sector I/O processing, you access 
records relative to the name of the I/O area. Otherwise, you must specify’a register 
(IOREG keyword parameter) used by the card processor to supply the starting address 
of the current record or must specify a work area in the DTF declarative macro, 
WORKA=YES. 


If you use multisector..processing, to determine the number of. sectors read by: one 
physical 1/0 as a result of a GET macro, divide your DTF blocksize length by the block 
length field in the file label (positions 22—26). The result must be an integral number 
of sectors. There is no remainder. The GET macro reads a block of sectors and points to 
a record or moves it to a work area until reaching end of data (EOD). Data management 
then passes control to your EOFADDR=symbol routine indicated on, the DIF macro.. 


Format: 
LapeL =| |) AoperationA =| OP ERAND 


ries tie | 


[name] 





Positional Parameter 1: 


filename” ~ aoe Pimeki: - 
Is the label of the corresponding DTF macroinstruction in the program. 
(1) eo ee ag 1 « £° 
Indicates that register 1 has been preloaded with the address of the declarative 
_macroinstruction. 


Positional Parameter 2: 


workarea 
Is the label of an area into which the current record is moved for processing. 


— 
fo ts 
, 4 
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3.4.2. Retrieve Next Logical Record: (GET) 


Function: 
_ The. GET macroinstruction makes the ‘next logical. record in an input file available to 
you. The data is accessible either in the I/O. area or jin-a-work area. you have 
specified. The macroinstruction is used for all record types. 


If you specify only one I/O area, you may directly access data relative to the name of 
the I/O area. Otherwise, you must specify a register (through the IOREG keyword 
parameter) to be used by the logical IOCS to give the starting address of the current 
record, or you must specify a work area in the declarative macroinstruction. More 
than one work area may be employed, since the address of the area is specified to the 
logical IOCS with each GET macroinstruction. Each GET macroinstruction may specify 
a different work area, if necesary. 


Format: 








A OPERATION A OPERAND 


filename ~ workarea 
a i 0) t 
1 0 











Positional Parameter 1: 


filename 
Is the label of the corresponding DTF macroinstruction in the program. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the declarative 
macroinstruction. : 


Positional Parameter 2: 


workarea 
Is the label of an area into which the current record is moved for processing. 


(0) or O 
Indicates that register O has been preloaded with the address of a work area. 


If omitted, indicates the user has chosen processing either by means of a register 
(LIOREG keyword parameter) or by directly accessing the data relative to the name of 
the I/O area. 

NOTE: 


When a work area Is specified, the keyword WORKA=YES must also be specified in 
the DTF statement. 
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Example: 


LABEL eeneneNe OPERAND A 
16 


1 
eRe ii. | wer. | Npom, INWoR 


Places the next record of the file described in the DTF macroinstruction, whose label 
is. INPUT, into the area whose label is INWORK. The optional label HERE may be used 
to reference this point in the’ program: 


ery, 
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(0) 
Indicates that register O has been preloaded with the address of a work area. 


If omitted, indicates the user has chosen processing either by means of a register 
(IOREG keyword parameter) or by directly accessing the data relative. to:the name of the 
I/O area. 


NG TE: 


. When workarea is specified, the keyword WORKA= YES must also. be: specified in the 
ere statement. Pes 3! 


Example: 
LABEL” AOPERATIONA _ OPERAND | _ A 


“Beer Te te PUT, LNWORK 


Places the next record of the file described in the DTF macroinstruction, whose label is 
INPUT, into the area whose label is INWORK. The optional: label HERE may be used to 
reference this” pot in the piegiam. - 
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PUT 


5.4.3. Writing a Diskette Record (PUT) 
Function: 


The PUT macroinstruction delivers an output record to the card processor. In single- 
sector processing, each PUT macro writes’ a record to. diskette. In multisector 
processing, you use the IOREG or WORKA specifications in the DTF and the PUT macro 
to control the release and writing of individual records from a block of sectors held in 
the output buffer to the output file on the diskette. . 


To prevent occurrence of unwanted information in the data, you must be careful to 
clear output record buffer areas before each use or, to supply complete records 
a: blanks on each logical PUT. | 


Format: 
LABEL: (| ~~ AOPERATION A. - -OPERAND 


au \ f ee ] 


[name] 





Positional Parameter 1: 


filename 
Is the label of the corresponding DTF macroinstruction in the program. 


(1) 
Indicates that register 1 has been preloaded with the address of the declarative 
macroinstruction. 


Positional Parameter 2: 


workarea 
Is the label of the work area from which the record may be obtained. 


(0) 
Indicates that register O has been preloaded with the address of the work area. 


If omitted, indicates you have chosen processing either by means of a register (IOREG 


keyword parameter) or by directly accessing the data relative to the name of the I/O 
area. 
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NOTE: 


When the work area is specified, the keyword parameter WORKA=YES must be present in 
the DTF statement. 


Example: 


LABEL AOPERATIONA OPERAND ‘ A 
ee 16 2 


1 1 : 
Spee tay 1.1,)., SUTWORK 


Programming Considerations: 
= ~=Variable-Length, Unblocked Records 
You must determine the size of the output record and must insert the size at the 


beginning of the record before issuing the PUT macroinstruction. Record size includes 


the 4-type record length field. You may not access the first four bytes, which are 
reserved for block size. 


UP-GUDG HeV.4 DPENHY- UNIVAL Ud/ 3 ee 
BASIC DATA MANAGEMENT “oe 


CLOSE 


5.4.4. Closing a Diskette File (CLOSE) 
Function: 


_ The CLOSE macroinstruction transfers control to a data management CLOSE transient 
routine which validates devices. If devices are diskette, a new diskette close transient 
receives control and determines the close processing required according to file type. It 
marks the DTF of an input file closed and resets indicators and fields in the DTF where 
applicable (2.4.3). For output files, it writes all necessary buffers to diskette; updates 
the EOD indicator in the file label, and resets indicators in the DTF before closing the 
file (2.4.4). The diskette close transient closes combined files like output files except, 
when updating or not updating the EOD field for partial updates of files or extended 
writes to files e 4.5). . eon Br a 


Format: 





A OPERATION A OPERAND 





fiiename-1 [,...,filename-n] 
(1) 
*ALL 
Positional Parameter 1: 
filename 
Is the label of the corresponding DTF macroinstruction in your program. Filename 
may contain a maximum of seven characters; the maximum number of filenames 
po is 16. 
(1) | 
Indicates that register 1 has been preloaded with the address of the DTF 
macroinstruction. 
*ALL 


Specifies that all files currently open in the job step are to be closed. 
Example: 


LABEL AOPERATIONA , OPERAND A 
1 10 
EnDRer, . | rese ePu 


Enters the transient routine which closes the file described in the DTF 
macroinstruction whose label is INPUT. 


aS. 
io 
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«Cb. Printer Formats 
and File Conventions 


6.1. GENERAL 


The section describes the data formats and file conventions that apply to printer 
subsystem files supported by OS/3. The SPERRY UNIVAC 0773 Printer Subsystem, an 
integrated printer, is intended primarily for use with OS/3. However, the SPERRY ae 
0768, One: and D110" Printer Subsystems are also supported by, OS/3. . 


A number of terms, asda i in what follows, se eniuinga here: 


line spacing 
Advancing the paper (or forms) to be printed under the control of a line counter, 
i. e. a specitied number of lines. 


line skipping te 
os Advancing the paper to a line on the form that is specified by a code placed in 
the vertical format buffer (VFB) by the user (or by a punch made by the user in 
the forms control loop). 


paper advance 
_ Vertical movement of. the. form or paper in the printer either after printing or 
| without printing. | ~ 


vertical folmat buffer 
A buffer in the 0773, 0770, 0768, and 0776 printers. The ‘buffer contains a 
location for each line on a form. A code may be placed in the location that 
corresponds to a particular line. Your program can then advance the form to that- 
line by issuing a skip command and specifying the appropriate code. The paper 
tape Joop on the 0768. printer is used. in Conjupetion with the VFB... 


load code buffer. ' 
A buffer located in the printer that allows the Specification of any 8- bit code for 
- any graphical symbol.on the print band or drum. Thus, you can load the EBCDIC 
. codes for the graphical characters on the print band into the. load code buffer in 
the proper sequence and then print EBCDIC data. WYSE “. 


UP-8068 Rev.4 SPERRY-UNIVAC OS/3 ~ 6-2. 
BASIC DATA MANAGEMENT  ~ : 


6.1.1. 0773 Printer Subsystem 


The 0773 printer has a standard print line of 120 print columns. You can expand this to 
144 print columns through available hardware options. Line spacing (6 or 8 lines per inch) 
is accomplished through a switch on the printer. Paper advance (up to 15 lines) is 
controlled by:the VFB and can be accomplished after printing or without printing. 


6.1.2. 0770 Printer Subsystem 


The 0770 printer allows you to use print lines of up to 160 print columns. The line spacing 
(6 or 8 lines per inch) and paper advance (up to 15 lines) are accomplished through the 


VFB. As with the 0773 printer, paper advance can be accomplished wou poning or 


after printing. 


6.1.3. 0768 Printer Subsystem 


The 0768 orintar allows you to. print lines of. up to 132 print columns. ine: spacing (6 or 8 
lines per inch) is controlled through a punched paper tape loop (forms control loop), and 
paper advance (up to 15 lines) can be accomplished without printing or after printing. 


6.1.4. 0776 Printer Subsystem _ 


The 0776 printer allows you to print lines of up to 136 print columns. Line spacing (6 or 8 
lines per inch) and paper advance (up to 15 lines) are accomplished through the VEB. As 
with the. 0773 printer, paper advance can be accomplished without printing or after 
printing. | 


6.1.5. 0778 Printer Subsystem 


The 0778 printer has a standard print line of 120 print columns. You can expand this 
optionally to 132 print columns. Line spacing (6 or 8 lines per inch) is accomplished 
through a switch on the printer. Paper advance (up to 15 lines) is controlled by the VFB 
and can be accomplished after printing or without printing. 


6. 2. FILE ORGANIZATION 


A ariit file can be Bet described as a > collection of related data that’ is output to a printer 
device, one line at a time (band or drum printer). Line printers assemble the contents of a 
complete Ine oe pen epaces) before actual printing occurs. ; 


Line: printers are brovided with the 90/30 system: and operate through OS/3. Therefore, 
not only are you-responsible for organizing the data you'want printed within each line, but 
you must also consider the vertical separation between lines and pages. 


Oh, 
4 
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Print files described in this section fall into three categories: 
udenietal text; 
“tabular data; and 


- dete sented on Gone: 


6.2.1. Text 


The simplest printer file to understand and use is probably one which consists of plain 
text. For example, assume that each input record is punched card and each output record 
is formed in the.|/O area or ina work area you have specified. The records are output to 
the printer buffer by the physical lOCS. Each time that the printer buffer is full, a print 
“command is issued and the line is printed. Figure 6—1 is a typical example of text output; 
the annotations point out the record where the home paper instruction should be issued 
and the home paper position necessary to begin printing the lower portion of the text at 
the top of a new page. 


LINE TRUNCATED (BIT 0) 


‘ WERTICAL -. . ; 

“spacine. FIXED LENGTH, UNBLOCKED RECORDS! THE LINE TRUNCATED BIT IS SET 

lake DURING OPEN PROCESSING IF THE USER HAS SPECIFIED A BLOCK SIZE 

~. .. \WHI'CH INDICATES A PRINT LINE LONGER THAN THE MAXIMUM PRINT LINE 

6 Lines/incH WHICH CAN BE PRINTED ON THE ASSIGNED PRINTER. OPEN PROCESSING IS 
COMPLETED AND THEN A BRANCH. TO THE USEK ERROR ROUTINE OCCURS. IF 
THERE IS NO ERROR ROUTINE, THE OPEN ROUTINE RETURNS TO THE USER 
AT NORMAL RETURN POINT. IF THE USER CONTINUES PROCESSING EACH 


PRINT LINE WILL CONTAIN THE MAXIMUM NUMBER OF PRINT 
HOME PAPER - ve 
INSTRUCTION 
HOME PAPER 
POSITION 


90730 PRINTER SYSTEM/USER INTERFACE 


: PAGE POSITIONS WHICH CAN BE PRINTED ON THE ASSIGNED PRINTER- 
HEADING 


VARIABLE LENGTH», UNBLOCKED RECORDS AND~DEFINED RECORDS: 
IF THE USER TRIES TO PRINT A LINE LONGER THAN THE MAXIMUM LINE 
LENGTH INDICATED BY THE BLOCK SIZE SPECIFICATIONs A LINE EQUAL 
IN LENGTH TO THE MAXIMUM INDICATED BY BLOCK: SIZE WILL BE PRINTED, 
AFTER THE LINE IS PRINTEDs THE LINE TRUNCATED BIT WILL BE SET AND 
A BRANCH TO THE USER ERROR EXIT OCCURS» if THERE IS NO ERROR EXITs 
THE PUT ROUTINE RETURNS TO THE INSTRUCTION AFTER THE PUT MACRO 
INSTRUCTION+ ‘NOTE: THE OPEN ROUTINE ADJUSTS: BLOCK SIZE ,IF A PRINT 
+ LINE LONGER THAN. THE MAXIMUM PRINT LINE.ON THE ASSIGNED PRINTER 
IS INDICATED BY THE BLOCK SIZE SPECIFICATION-e IN THIS CASE» BLOCK ~ 
SIZE 1S ADJUSTED TO- INDICATE A MAXIMUM PRINT LINE EQUAL IN LENGTH 
TO THE MAXIMUM PRINT LINE ON THE ASSIGNED PRINTER- 





Figure 6—1. Typical Text Output Example 
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6.2.2. Tabular Data we @ See Se gat 


Tabular data and reports generally require a more complex printer file structure:since 
there is a more varied spacing requirement, both vertical and horizontal (Figure 6—2). 
Also, column headings and similar repetitive items require a more complex program if the 
file is lengthy. The output records are formed in the same manner as those of regular text 
files (in the |/O area or work area) and are output to the printer one line at a time. 


HOME PAPER POSITION 






. ee _DAILY. acTIVITY REPORT 
COLUMN § | -_ TRANS- 7 QuAN DEPARTMENT 
HEADINGS |_ ee 
“PRODUCTION 
_) PRODUCTION 
|. MAINTENANCE 







DESCRIPTION ; ACTION | les dou ON- “HAND mas, @ oe 
CAPACITOR ORDER «'. 

. ~ ROTOR. ORDER ~ 

00010G POINT» IGN ORDER . 





Figure 6—2. Sample Table Printout 


6.2.3. Printer Forms 7 | BS ee : die 


Printer files that complete or that are added to document forms are usually simple to use 

once they are organized (Figure 6—3). By using. | the control’and overflow — —_ 
macroinstructions, you can achieve desired vertical positioning. By forming your records ah 
properly in the |1/O area or work area, you can achieve the required horizontal positioning | 

to place the data on the form where it belongs. ) 


SPERRY <> PUNIVAG 


Co syY STEMS 


P. 0. BOX 500 
BLUE BELL, PA. 19422 


HOME 
PAPER =—=———~--T 
POSITION qe & Hz SITE 3- 1 
ATTN: CATHY SM! 
HOME PAPER, _'|___. _D6866M 8598 — UP 8071: 


INSTRUCTION .-. : 7 ADDRESS CORRECTION REQUESTED 
oo a : i ae : RETURN’ POSTAGE GUARANTEED 


. ‘uD+827 





Figure 6—3. Sample Forms Printout 
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6.3. RECORD FORMATS ___ 


You have the option of specifying, in the DTFPR macroinstruction, that a control character 
is to be included in the data records. This character specifies line spacing or skipping 
when the file is printed. The character itself is: normally not printed, but is a part of the 
record in storage. If: the record is sent toa printer and the user has not specified that the 
record contains a control character, the character is handled as data and printed. ioe 
areas must be large enough to include this character. sot 


When fixed-length or undefined record formats are used, the control character is the first 
character in the record (Figure 6—4). It is the first character following the record length 
specification in a variable-length unblocked record format: The block size of the output 
area must include the byte for the control character. If variable-length, unblocked records — 
are to be processed, the block size must account for the initial eight characters as well as 
the control character (nine bytes total) in the output area. Although these characters do. 
not appear in the output, the output area must be large enough to accommodate them. 
When a control character is specified, every record must contain a control character. 


When a PUT macroinstruction is executed, the control character in the data record is- 
translated to. the appropriate command code.. (For the. character required,.see the CTLCHR 
keyword parameter under the DTFPR macroinstruction, 7.3.) The first character in the 
output data after the control character is the first character printed. Logical input/output 
control system (IOCS) modules also automatically issue certain printer control instructions. 
These involve printer overflow conditions and vertical format control. Parameters available - 
with the macroinstructions that call the IOCS modules into the program allow you to tailor 
them for each particular task. In this manner, the complex vertical movement and overflow 
sensing functions are rade easy for you to control. 


If the CNTRL macroinstruction is to be issued for the printer, the CONTROL ‘keyword 
parameter is specified and CTLCHR must be omitted. 
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Fixed-Length ‘aL aes ee K 


data, fixed length 





Undefined 


data, variable length 


SSS 


Variable-Length 





data, variable length 





LEGEND: 
b 
cc 
r 
u 
D 
A 
Cc 
F 


NOTES: 


Block size field, four bytes 

Control character, one byte, optional 

Record length field, two bytes, binary : : Pee 
Reserved (two bytes); can be any two characters you ‘choose. rs A, Mees 
Record size field 

Data record length 

Variable record length 

1/O area layout 


1. You must align an |/O area so that the first character to be printed falls on a half-word boundary. 

2. You must place record length, as a binary number, in the first two bytes of the record length field (r) before printing a 
variable-length, unblocked record. The record length includes the 4-byte record length field and the control character, 
if any. 


3: You should allocate an even number of bytes for data in |/O areas, even though an odd number of columns are to be 
printed. To print an odd number of columns, allocate data areas one byte larger than the number of columns to be 
printed. 


Figure 6—4. Printer Record Formats 


pitta, 


CN 
f > 
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6.4. VERTICAL FORMAT AND LOAD CODE BUFFERS 


In OS/3, you use the job control LCB statement to specify the load code buffer (LCB) and 
the VFB statement to Specity the vertical format ‘buffer ae of the following) printer 
subsystems: : 


m SPERRY Eee 0768 Printer Subsystem : 
. enn UNIVAC O770 Printer Subsystem 
=m SPERRY UNIVAC 0773 Printer Subsystem : 
m SPERRY UNIVAC 0776 Printer Supsyetem 
m SPERRY UNIVAC 0778 Printer Subsystem | 


Refer to Table A—3 for operational characteristics of these printers, aud to the job cori 
user r guide, UP- 8065 (current WereiOn 


6.4.1. Load Code Buffer Interchangeability 


There is no imerehangeability: of printer load code’ buffers across aeyviees: an LCB job 
control statement you have aes fora parieular Bees and paint pave or eal cannot 
be used for any: other. 


6.4.2. LCB Sensei Specification 


You specify the codes to be assigned to each speaiie symbol on the print band or dean by 
using the X (hexadecimal) or the C (character) positional parameters of the LCB statement. 
You must specify a character code or a hexadecimal specification for each symbol on the 
band or drum, and you may intermix:X and C specifications. Each X or C specification 
must be complete on a single card. As many specifications as are necessary to specify an 
entire band or a single repeated font may be made. 


The space or nonprinting code should be specified:through the SPACE keyword parameter, 
and not included in the sequence of codes specified through the positional parameters. 


If the number of characters is specified with the NUMBCHAR keyword, it should include 
only the number of codes specified for graphic symbols and should not include the space 
code. 


If the CARTNAME keyword is specified, the operator receives a message to mount the 
specified band, and program execution is suspended until the operator replies to the 
message. If the CARTNAME keyword is not specified, no operator message is issued. 
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6.4.2.1. LCB Specification for the 0773, and 0778 Printers | 

You may specify 48, 63, 64, or 256 characters for the 0773 and 0778 printers; however, 
any band having more than 64 characters requires:the specification of 256 characters. A 
128-character cartridge requires the specification of 256 characters. A 128-character 
cartridge requires that the 128 characters be epocited twice on the LCB statement. 
Dualing applies to 48-character bands Sai: you specify saating with ihe » DUAL keyword of 
the LCB statement. Four dua/ling characters may be specified for the 0773 and 0778 
printers; these correspond to the 39th, 40th, oa and 47th Copnectels on the band. 


The CARTID specification is optional for the 0773 andl 0778 srinters: 


6.4.2.2. LCB Specification for the 0770 and 0776 Printers 


You may specify from 24 to 384 characters for the load code. buffer of the 0770 and 0776 


printer. For repeating fonts ranging from 24 to 192 symbols, you. need only specify the 


characters for a single font: for example you would specify only 128 characters through 
the LCB statement for a repeating font of 128 characters. 


Dualing for the 0770 and 0776 printers involves earings up to aun pairs of codes with 
the DUAL parameter. Each pair consists of.one code that has been specified for the load 
code buffer, followed by one code that has. not.. Assuming, for example, that a band 
contains the question mark symbol (?), but not the vertical bar (|), you could substitute ? in 
your printout for | by specifying DUAL = C?|’. Every time your program outputs the EBCDIC 
code for a vertical bar to be printed, a question mark appeals on the Ponies listing. 


For the 0770 and O776 printer, you must specify the CARTID sea eieen and the code you 
epEcity must be the correct one for the: cs you WEES to use. 


You may. aise specify a ai smaich character for the 0770: or 0776 srintet: that is, you may 
specify what character, other an blank pace) As: ‘to be penis whenever a character 
mismatch occurs. ; 


6.4.2.3. LCB SpecIncAHon for the O768 Printer 
You need ealy specify the string of codes for ‘ine load code buffer and the MISM, SPACE, 


and TYPE parameters. You may also specify the optional NUMBCHAR parameter, but the 
other parameters of the LCB statement do not. apply to the 0768: printer. | 


oO“ 


ike 
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6.4. 3. pNETUEAL) Format Buffer ierchanigeabiity’: 


Table 6-1 summarizes Sahel conditions under which a. cacti enacitiea VEB | statement for 
one printer may be used with other devices. There is no difference in the appearance of 
the printed results if the same VFB statement is used from mgenine to machine under 
these eahetuions: : ' a ; s oe 


6.4.4. VFB Statement Specification: 
Specifying a VFB job control statement involves visualizing the form. with numbered lines. 


An 11-inch form to be printed at a density of 8 lines per inch has 88 lines. At 6: lines per 
inch, an 11-inch form has 66 lines. The first printable line on a form is line 1. The last line 


on, an 11-inch form, printed at 8 lines per inch, is’ ling’ 88. 


The vertical format buffer can be eueniiad and the program eae so that most printing 
occurs between the home paper code position and the overflow code position on the form. 
The position of the home paper code. determines the amount of unprinted: space at the:top 
of the form, and the overflow code Peeen BPPrORIMeReS, ne amount of aanprimad ee at 
the bottom. of the FOEM: ee ‘ir ok FA ye. Se 


Because lines may be seinted (and the, form seivineedl bevend the overflow position, you 
must provide enough space between: the overflow.code position’ and the bottom of the 
form for any lines (and form advances) that must fit-on.a page. Note that you must provide 
at least four lines between the overflow code position and the bottom of the form. This is 


particularly tnpentant for VFBs that are. used to. enn piss nbteran runs, Besoin, 


etc. 


6.4.4.1. Specifying Home Paper Position 


The HP code specified on the VFB job control statement gives the lines number location of 
the home paper position: The specification HP=5 places the home ‘paper .position on the’ 
fifth line of the form. 


6.4.4.2. Specifying Forms Overflow Position 


You use the OVF keyword of the VFB job control statement to specify the forms overflow 
position to printer SAM. You should not specify. the OVF keyword if. you do..not intend to 
use it. 


When an overflow code is. placed in the buffer, a space form operation:(advance paper n 
lines) which would move the form to or beyond the overflow position causes forms 
overflow to be detected. On detecting forms overflow, printer SAM takes action according 
to your Sper incayons of the rere ee peremere in rue mess declarative 
macro. oo. , as 
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No indication of overflow is returned to you, except that printer SAM transfers control to = 
your overflow routine if you have so specified. In this routine, you may take such actions ws 
as skipping. to the rep of the next page, pie pager numbers; puemung subtotals, aoe so 

forth. : | 7 , | | | 


You must Sheen the avediow code Sasition so that eacugh space is io Reareen the 
overflow position and the bottom of the form to print and space all of the lines that are to 
appear on the page. Printer SAM may print a line on or below the overflow code position 
and perform spacing before branching to your overflow routine. ; 


If a PUT appears in the overflow routine, the effect will be to perform Spacing anger print 
a. line merween the. overlow Posten and the porom of the form. 


If the user does not Speci the PRINTOV kevwerdi in the DTF, data management takes no 
overflow action; in this event, the BAL programmer who is not counting lines in his 
Program runs some ner ‘of tearing re torn bY pe on or ‘too near the peroralony: 


Table: 6—1 summarizes ‘fie combinations of devise: independent control eneiacter codes 
permitted when using each type of printer’ with: or without ‘the TYPE | parameter 
specification on the VFB job control statement. Because it describes the allowable use of 
device-independent control character codes, Tables 6—1, 7—1, and 7—2 should be used 
conjunctively. Table 7—1 interprets the’ control character codes associated with each of 
four printer. functions: print and space, print and skip, spacing; and enpIng: Table 7-2 
inter piel oyemlew: and home: paper control charscir eOdes: aa Hee 


f 


Note: that the 0770: srinter has two. diaHiows codes: (9 and 12) that the data ihanadgerierit 
PRTOV imperative macro can detect selectively. You should specify a secondary overflow 
code (hexadecimal code Q9, specified through the OVF2 keyword) only with the 0770 printer 
and only if you are using the PRTOV macro, or su yeu are > not Boing. data management: its 
PIOCS equivalent. 


6. 4.4. 3. a Specifying Special Forms | 

If you specify the FORMNAME keyword in the VFB job control statement, the operator is 
issued a message to mount the eperined:! form, and program execution is halted aed the 
operator replies. 

6.4:4.4. Paper Tape Loop, 0768 Printer 

For the 0768 printer, you must provide both a paper tape loop and a VFB job control 
statement. The paper tape should be. panenes. to agree exactly with the’ oe Statement, 7 
with the following exceptions: ae 
1. | A 7 should not be punched on tiie tape. Home paper should be sneha either as’ 15 


(for 8 lines per inch spacing) or as 14 (for 6 lines per inch). Only one home paper 
code may be punched on the tape. 
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2. Channel 1, 2, 3, or 12 should not be punched on the tape. :::. ie ne 


Table 6—7. VFB Statement Shaciiication: ahd Witechangeabiiny a EES, ty Le 


Statement May 
Specification of be Used With Other Reoveeie that the User ey Bpecity Nae 1): 


TYPE Keyword | Printer Types _ 
(Note 2). 


= 0768 TYPE 
ore 0770 keyword 


pane _| 0776 omitted 
os 0773 


0778 


TYPE 
keyword. 
omitted 


TYPE 
keyword. 
omitted 





x Keyword may be specified. Sh hg ess 

Keyword may not be specified. 

NOTES: ; = By ate » 4 Fa PES Se: Pat aoe 

1. This table is eopeerned. with ud the keywords shown; the user cmay always specity te LENGTH, DENSITY, FORMNAME, and USE keywords. 


2. The TYPE Keyword should be specified only if a : particular printer type must be used. A VFB statement designed | fie a “particular printer. (using the 
permitted keywords shown for that printer in Table 6—1) may be used with other printers only if the TYPE keyword i is omitted. 


3. The user should specify TYPE=0770 only if he specifies a secondary overflow code (OVF2) or if he specifies multiple home paper positions. 
4, If the user does not specify the OVF2 keyword, he may use the VFB statement (TYPE keyword omitted) with the 0768, 0770, and 0776 printers. 
5. The secondary overflow code (OVF2) should be specified only by a data management user who issues the PRTOV imperative macro. Refer to the PRINTOV 


keyword parameter of the DTFPR and PRIO declarative macros. 
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6.4.4.5. Vertical Format Buffer Statement Example 


The following example might be a typical VFB statement used to set ae the forms spacing 
and skipping required for a printed: report. 


LABEL DorERATIONA. a) ., . OPERAND } A COMMENTS _ 
//_ NFB LIENeTH=lb6,, DENSITY =i6, FORMNAMES TESTOR, TYPE=OTI70,HPI=,,ONIFE52.5| 








[iai-coack CD HPO ib ee ad - 


“Line 1 specifies that the operator use a form called TESTPR. The total number of lines per 
page is 66 at 6 lines per inch. The 0770 printer is being used. The home paper position is. 
on line 1 and the overflow area of each page begins on line 52. Note that this includes the 
4-line space between the overflow code position and bottom of. page used if a dump, 
librarian run, or assembly is executed. The number 52 is used: by data management to test 
for page’ overflow conditions. Then, according to your PRTOV imperative macro 
specifications, .data management skips to the overflow routine or register to handle your 

overflow routine address. 


; Line. 2 specifies a channel code of CD2 with a line number of 6. This means that 
whenever a CNTRL filename, SK,2 imperative macro is issued in the program, the printer 
immediately skips 6 lines on the page. Here a detail line of a report might be printed. On 
the other hand, if a CNTRL filename,SK,,2 macro is issued in the program, the printer 
skips 6 lines after printing the detail line. The first macro use illustrates immediate 
skipping and the second, delayed skipping. i 0 8 


A second channel code of CD3 indicates 46 lines. Similarly, the CNTRL macro could 
specify an immediate or delayed skip of 46 lines where a final total might be printed. 


It is important to realize that the CD number (VFB parameter) relates to a channel code 
and the value indicated on the right of the equal sign indicates the line number to, which 
the printer skips. 
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q, Function. and Operation 
of SAM Printer Files 


7.1. GENERAL 

The OS/3 includes data management: modules that can be used to move and manipulate 
sequential access method (SAM) printer is These modules’ can. function: with five 
diferent printer sand nila he: a R aed iv Ye =< 

2 - SPERRY UNIVAC 0773 Printer eS bevene 

=» SPERRY UNIVAC. 0770 PUNLOE: pa Aroale oo 

= SPERRY UNIVAC 0768 Printer Subaysienn 

= SPERRY UNIVAC 0776 Printer Subsystem 

= SPERRY UNIVAC 0778 Printer Subsystem 

This section contains a brief functional description of printer file SAM operation.- This is 
followed by a detailed description of the declarative macroinstruction that is used to define 


a printer file and of the imperative macroinstructions that initiate, conduct, and conclude 
file processing. 


7.2. FUNCTIONAL DESCRIPTION 


At system installation time, the system macro library (SY$MAC) is loaded with source code 
modules that are common to several machine operations. These modules include data 
management modules that are common to several device types and access methods. 


When assembling the program, you define the characteristics of printer file involved in the 
operation, using the define the file (DTFPR) . declarative macroinstruction. This 
macroinstruction creates a table of file characteristics, in main storage, that is referenced 
by your program. . i, = 
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The source code modules that are required for your program are called in from the system 
macro library at program assembly time by using imperative macroinstructions. These 
imperative macroinstructions are included in the program you are assembling and result in 
the creation’ of inline code at.the point where the assembler encounters the 
macroinstruction. Positional parameters contained in the imperative macroinstructions 
allow you to modify the basic . assembled module so that it meets your particular 
requirements. 


When the file is opened, the characteristics in the file control table set up by the DTFPR 
are examined to determine that they are valid and, if required, that they are present. The 
output records are formed either in the I/O area or a work area. A form of overlap 
processing can be achieved by assigning either two I/O areas or an |/O area and a work 
area. In this way, records can be constructed in one area while others are Sm UlbaneOUsly 
being output to the printer from the other area. 


Logical input/output control system (IOCS) modules also automatically issue ‘certain 
printer control instructions. These involve printer overflow conditions and vertical format 
control. Parameters available with the macroinstructions that call the |OCS: modules: into 
the program allow you to tailor them for each particular task. In this manner, the complex 
vertical movement and overflow sensing functions are made easy for you to control. 


A typical printer SAM operating sequence is described in the following example, which 
show the sequence and function of each macroinstruction. The macroinstructions are 
discussed in detail in 7.3 and 7.4. 


Example: 


LABEL AOPERATION.®: OPERAND -, “COMMENTS | 
10 


Titbcaiire in execute a ts Rane Saree ee 


Biden Eh UREY sat ieee hs Sel a eh Peete Bw 


M45 i i : : 
eh TEA x i Sooceal es wiatas, “ay Hi ele ea ly ate a ee ee a tel I SB ea Wee “ecg ES Ge & 


pater dita cs i cire ne, Cae eae aes ern ete ate use fe AS aes : oe ae Soa 


was He, Ae eee Mi ee eae nh Ne etd EO ys! tbe Sen ae 











Vera) areal Genes ee fm ae OTT tr ce | 





; i ff ‘ ; : : 
ict od se des acters Sal sobs eee Rae eek ty eg ie ek dies Bite y cde eRe We keys Gl Sa eh te 


-Keywe - t paramel tere ) de ine magnetic ape Inp We and 7 eo 
ee falas EE Sal a ada characteristics “? 


. en oe ee ees ee wt ee + - a ne Seen a er ene - 





. po? F 
Saeed .f Sgt oe oe Sarat ere ine Rares emery Ee esee! ned BO Nerd alicia. iv ah, dtaet te “ee oS 


| Sige definition ewer oe eee ee 


TAPELIIN 


ees ery 





aac een routines to check DTEMT and DTFPR that 
aa all mecessary parameters are supplied and are valid. The physical 
PRTDUT TOCS then reads the input recerd into the If area. 


oe 


Sei aie MN ste ss eee Se teas os UA a Se BO Bee Thich ak Se ey re OR ee a Ge a ce 


oe hn rs > hex F3) scora avatiab < D 
TARELN, WREAREA... racing iF inthe werk-ares; labeled WRKAREA. 


Ae ila aoe ng, BME Pees: S Bi 62 Sel Bk. Ces mittee Nas 


fe hates, Be ed aes ats Fh ctl sce gd Pe ta i eat EE ety Bea See le . i : re Se $a ie aa ee 8 - wa te, - . : . 


Pracessing steps Seah, dete ASE ee pag, ee Jetset sho ide & wr rk BOR Ten S 
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LABEL AOPERATIONA . OPERAND A COMMENTS 
10 16 





ad Be Vee ae CiN TRL Ma PROUT. 5.5.Ki5 7. : *M acrS specifies-ahrimmediate Skipto the. iii paper’ ee 
¥ poo toa fae ce es ee Doe pode eg) Pe eo itiim (code Tt) >befere: ante eae . Chet Ste 
¥, pele ee SD a ee oie ae Se ee eg ais ae eee ahs i ee ae hod it ret gente { 


| ay eae Va 
ped. OT WRK REA {Delivers anoutput recerd from the work area 
$a PUT - ARR TOUT. 9 — ‘Seales WRKAREA tothe put put area. 





| ots the recbrtd th the printer cae 


Mi Sh Me (ME Sleep me Sy © (cs 2 alt Wane WRN UO RN Stes A) RS Wea Soe GOS PURE meas We QR bane ee ae" e 
EST SA So ay Fel Ns ON Ne Us ae ees Cal Sk a eT aN SA De Sc DE es TSO CR CS ne aT Ee Ue 
| [pet av PpRTbur. 12. t EST aR PR YOEE EOOPG re HR ETN Cer WN OR SIP eC VS Fee EM ae ey 
ctl 1. | 
pecifies that ferme © effete OTTO Printer bang. Se ddl 
used will be indicated by VFB chde 12. 2, Ag the third ppsitinnal se 
parameter has been bmitted, an automatic Skip tb hor pete paper 
position, will peeve when ee ms exert low is eee ics wd 


ae ae ‘ae eee oe | 





i ito. ey i dea vee 
Tritiates file process ne sabes avettve et 
i Ree earns eas a 


fa ee eas RE a iL. 


ep Sh pee pl otk 
| : int H 





1 F 
i i oS 





ngs, € liy Fs tse ey ES Es RY Eas DPS EST Ege cae TD eons Ow re ee 


Wine (caer ee nee oR a SE eee sae aed Ea [eae ie ae 


_ a End? dij ata. : tt tara iinet Sige Sek is eee ee eel et 





* 









' 
SS Ee VO Ri a Rr eR RS Ge ens LC Oe a Ce Sm OO 
Executes proora ee ee Sao 
+ 2 =, 





ee ne igo eg oe a ee ae a 
Endofijpb 
eae eds eee ae ae OY oa ek Re Lae Ms Soe Re Pate a ese Nee ee 


fey a oe ee po i ee ee 
fe te 





eee Ne a eh Pa ed Soe 2 a ee Sa ces {.. 
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7.3. DEFINE A SAM PRINTER FILE (DTFPR) - 


Function: 


The DTFPR declarative macroinstruction is required to define each printer file 
processed in the program. Following the format is a listing, in alphabetical order, of 
the required and optional keyword parameters which may appear in the operand of 
the DTFPR macroinstruction. A description ofeach keyword parameter follows the 
format. A summary of the keyword parameters is given in Table 7—3. 


A comma is shown preceding each keyword parameter except the first, to remind you 
that all keywords coded in a string must be separated by commas. However, a comma 

--must neither be coded in. column 16 of a continuation line, nor follow the last 
keyword in the string. Refer to the coding example that follows. __ 


Format: 


LABEL 


filename 


AOPERATION A 





| [BLKSIZE=n] : 7 a ( 


_ OPERAND 


[,CONTROL=YES] a gs = 
[CTLCHR=DI] ee 
[,ERROR=symbol] | 

JOAREA1=symbol 

[ IOAREA2=symbol] 

[ JOREG=(r)]  ~ 

[ ,OPTION=YES] 

[,PRAD=n] 


PRINTOV= SKIP | 
symbol 
YES - 


UNDEF 
VARUNB 


[ ,RECSIZE=(r)] 
[ SAVAREA=symbol] 


[ JUCS= {e F MI 
ON 


[, WORKA=YES] 
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Keyword Parameter BLKSIZE: 


BLKSIZE=n | 
Specifies the length of the I/O area in bytes. If the record is variable length or 
undefined, n specifies the length of the longest’ block, including block size and 
record size bytes for the variable- sac unblocked records. 


if omitted, the block size (120, 121, 128, or 129) is determined from the CTLCHR and 
RECFORM keyword parameters. 


With RECFORM=FIXUNB specified and CTLCHR not sesteti block size is set to 120. 
With RECFORM=VARUNB and CTLCHR specified, block size is set to 129. 


The minimum block size is two bytes. With CTLCHR=DI, RECFORM=VARUNB, and 
maximum print position options installed on the 0773, 0778 and 0770 printers, block 
size can be a maximum of 141 bytes for the 0768 printer, 145 bytes for the 0776 
printer, 169 bytes for the 0770 printer, and 153 bytes for the 0773 and 0778 
integrated printers. If these optional features are not installed on your printers, the 
maximum block sizes for the 0773 and 0778 printer are 129 bytes and for the 0770 
printers are 141 bytes. 


Keyword Parameter CONTROL: 


CONTROL=YES 
Specified if spacing or skipping lines on : the printer is controlled by your program 
through the CNTRL macroinstruction. ; 


The CONTROL keyword parameter and the CTLCHR keyword parameter are mutually 
exclusive. If they are both used in the same DTF, an error yileg appears in nthe output 
listing and the control specification is ignored. 


‘Keyword Rabameter CIRCE: 


This keyword parameter i is epeciied: when you dish to use a ‘control character with 
data records. 


CTLCHR= DI ' a bait 
Specifies the device-independent, 2-digit, hexadecimal control <EhanSetse ads 
listed in Table 7—1. 


The use of device-independent characters allows a single character for each function 
to be used with any printer, even if the hardware opcode varies with printer type. 
With this set of characters, some substitutions have to be made to compensate for 
device characteristics (Table 7—2). 
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. Print and space 
n lines (Note 8) 


n= 


CHOWoOORWNR 


0 


Print and skip 
to code n (Note 7) 


n= 


Space n lines (Note 8) 
n= 


1 (OV) 
2 


3 
4 
5 
6 
7 
8 
9 


OMAN Oar WN— 
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Table 7—1. Device-Independent Control Character Codes (Part 1 of 2) _- 


Code 2 
Code 1 -(OV) 
Code 3 
Code 4 
Code 1 (OV) 
Code 5 
Code 7°: (HP) 
Code 7 (HP) 


Code 12 (OV) 


Note 4 (OV) 


Note 2 (OV) 


Note 2 (OV) 


Code 7 (HP) 
Code 7 (HP) 


Printer 


Chan 15 Note 3 | 


Chan 9 (OV) 


Chan 15 Note 3 


Chan 15 Note 3 





Code 12(0V) = 


— 
as 
J 


re 


Code 7 (HP) Note 4 


Code 12 (OV) 


Code 12 (OV) 


Code 7 (HP) 
Code 7 (HP) 


- Fy 
3 
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Table 7—1. Device-independent Control Character Codes (Part 2 of 2) 


Printer 


Function Gade 
(Hex.) 0773 and 0778 ° 0770 0768 one 


Skip to code n (Note 7) 

n= 1 (OV) Code 12 (ov) Chan9 (OV) Code 12 (OV) 
i Note 5 ~ 7 
Note 5 


N 


Chan 15 (Note 3) . Code 7 (HP) Note 4 


3 
4 
5 
6 
7 
8 


Code 2 
Code 1 (OV) Code 12 (OV) 
Code 3 

Code 4 : o a 
Code 1 (OV) Note 2 Chan 9 (OV) Code 12(OV) 
Code 5 a om 
Code 7 (HP) Code 7 (HP) — Chan 15 (Note 3) Code 7 (HP) 
Code.7 (HP). | ‘Code-7 (HP) >| “Chan 15 (Note 3) ~~ Code 7 (HP) 





LEGEND: 

OV = Overflow code 
HP Home paper code 
NOTES: 


1. Line spacing of 4- 15 lines on oe 0768 printer is accomplished by issuing multiple 110 commands. The commands are issued 
’ by data management. 


2. Code 12 is the primey forms overflow code on the 0770 printer. Code 9 can also be detected as forms overflow code, using 
the PRTOV macro. If the PRTOV macro is not used, however, code 12 should be used as overflow code; and code. 9 should 
not be placed i in the VFB. 


3. On the 0768 printer, you must use both a vertical format buffer and a paper tape loop. Using DI codes 27, 2E, or 2F as 
control. characters has no direct effect on line spacing; this is controlled by what is punched on’the paper tape loop. The actual 
selection of six or eight lines-per- -inch spacing occurs when the operator sets ‘up your form on the 0768. printer to register at 
home paper position and pushes the HP button twice. 


1f channel 14 is used as home paper code on the paper tape loop, this causes printing at six lines per inch; using channel 15 
results in eight lines-per-inch spacing. These two codes should not be intermixed. When a DI code for skip to code 7 is issued, a 

skip is issued to channel 15 on the 0768 printer —.this causes an advance to either Shane! 14 or 16, whichever in punched on 
the paper tape loop. : 


4. Code 7 must be used as the home paper code on the 0770 and 0776 printers. 
5. For the 0768 printer, the software (physical |OCS) provides codes 2 ane 3 
6. Line spacing (print density) is switch-controlled on the 0773 and 0778 printers. You issue instructions to the operator via the 


job control VFB statement by using its FORMNAME and DENSITY parameters, and he sets the line rate when the vertical 
format buffer is loaded. 


. For the 0770.and 0776 printers, line spacirig.is software-controlled.via the DENSITY parameter of the VFB statement. 


7. Code n specifies channel code CD1 through CD15. (See-7.4.3.) 


8. Code n specifies number of lines to be spaced. (See 7.4.3.) 
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- Table 7—2. Overflow and Home Paper Control Character Codes 


| 0773 and | ee ae me 
0778 an .0768 0776: . 
Code 1 Code 9 Code 9 Code 12 A. 
ial Code 12** |... oe 
Home paper Code 7 7 Code 7 Code 14 Code 7 
Code 15 


*Code 12 is the primary code; code 9 should not be used with the 0770 printer unless the. 
PRTOV macro is used. i i . 














Overflow 





Keyword Parameter ERROR: 


ERROR=symbol |... tad | ; | 
Specifies the address of a special error handling routine to which you ‘may have 
control transferred when a fatal hardware or detectable logic error occurs on 
your file. Information concerning reasons for the error will be contained in 
filenameC (see B.4). 


Keyword Parameter IOAREA1: 


IOAREA1=symbol | ( 
Defines the address of the I/O area. Each input or output file must have an area 
~~ reserved for its individual use. The I/O area must be aligned so that the first byte 
of data (the character to be printed in column 1) is on a half-word boundary. 
The I/O aréa must provide ‘space for everything included as part of the block length. 
You must allocate |/O areas that contain an even number of bytes, excluding the 
control character, if any. Data-management inserts a nonprinting character at the end. 
of any user’ print line which contains an odd-number of characters. This extra 
‘character is placed in an I/O area before printing the line. — ae ea 


Examples: 


LABEL - NOPERATIONA OPERAND AT 
10 16 


DIS, 1 | | Tow sane i % iH,a,| f=) ord iaLig me init 





De... |b fale er Hal £.-wer.d, jalioniment 
Ae i ae ae RS 
THAI... | bs... | Ibeenn....1....1 IDAREAL 1... 4. 7 
emer eee i awe be, YT Eediria, bytes. ta = 
TOAZ 1... | iS... | (DCunn i IPAREA2 


a ; 


v 
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Without control character: nn must be even and greater than or equal to 
BLKSIZE. 


With control sCnEraereE nn must be odd and arate than or equal t to BLKSIZE. 


Note, in this case, that it is necessary to reserve one ‘ite after the half-word 
alignment, because the first character to be printed must be on a half- -word 
boundary, and a control character is being used. Remember that the block length 
always includes one byte for the control character when one is aused, 


eee Parameter IOAREA2: 


IOAREA2=symbol 


Provides a second I/O area to ailGid egetianpan processing and speed |/O 
operates 


; The same condition ‘hak apply for IOAREA1 also apply for IOAREA2. If IOAREAZ2 is 
specified and WORKA is not, you must specify the IOREG keyword parameter. No. 
additional processing speed is obtained when both the IOAREA2 and WORKA 
‘keyword parameters: are species: met efficient processiiig is obtained with either of 

” the rolewing 


IOAREA1, IOAREAQ, and IOREG 
or 
IOAREA1 and WORKA 


ses bagi Parameter lOREG: 


-1OREG= (r) 


Specified when a : general registér 2 througtt 12) is. Rigee to reference current 
data. If SAVAREA is specified, register 13 is also available. The register must be 
specified. a two aes areas are deed us Feeorgs are not to pe processed ina 


ae work area. 


After etich line is. srtnted, and’ ‘before’ returtiing to your program, data management 
loads the register specified by IOREG with one of the following, depending on your 
record format 


7 The. address where the first characte of the next recoid:t to “bie output should be 


placed when fixed-length, unblocked or undefined records are used. This is ees 
a control character (if used) or the character in print position:1. 


~ The address of'the location where: the 4-byte' record length field, followed by the 


control character, if any, and data to be Ailing should be eee for variable- 
length unblocked records. 


The IOREG and WORKA keyword parameters are mutually exclusive. If both are 
specified, the WORKA keyword parameter is ignored and an error flag appears in the 
DTF listing. 
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Keyword Parameter OPTION: 


OPTION=YES 
. Allows you to specify an optional file: one -which you anticipate will not invariably 
be required to be printed every time your phegram is executed. 


When the OPTION keyword. Saraieter is used,. the PUT, CNTRL, and PRTOV 
imperative macroinstructions are disabled: ; 


= if an OPT positional parameter is included in the DVC job control statement and 
the device is not available at execution time; or | 


= when no device is assigned to ul file by your job control statements, (i.e., no 
DVC-LFD sequence). ; 


If the OPTION keyword parameter is used under these conditions, the occurrence of a 
PUT, CNTRL, or PRTOV macroinstruction results in a praness back to your. program, 
: ane no I/O is PRUORMet: 


if ‘the OPTION aware. parameter is not specified and one oi the two previously 
stated conditions exists, the file is not opened; an error bit is set in the file table and 
the program branches to your error routine. If yeu have not provided an error routine, 
control returns to you inline. as 


Keyword Parameter PRAD: ar ar a. ee -~ 


PRAD=n 
Allows you to specify a standard form advance of from 11 to 15 lines, ater nis 
the number of lines the form is to be advanced and ranges from 1 through 15. 
_ The form aINance: takes place after the. line is printed. - F 


‘On. the 0768 SHINee Spacing. a 4 ihrough 15: lines ‘is accompishedaby issuing 
multiple 1/0 commands because this device can advance only three lines under one 
1/0 command. If the PRAD and CTLCHR keyword parameters are not specified, 
PRAD=1 is assumed; if both are specified, the control character will determine the 
line advancement.. ; my 


A delayed CNTRL macro instruction, which spaces or skips lines after printing, 
~- overrides the PRAD. REY WOT: parameter SpScirigaHon for one penn operation only. 


keyword Parainetar PRINTOV: 
This keyword parameter specifies the action to be taken when the forms overflow 


code is detected during a space or.print and space command. The forms overflow 
code cannot be detected on skip or print and skip commands. 
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There are three PRINTOV option specifications that can be made: 


PRINTOV=SKIP ae 
Specifies an automatic sido to sihe home paper position. 


PRINTOV=symbol 
Specifies that control is “tveueterred to your -avertlows routine. When this 
option is specified, the form will not be automatically advanced to the home 
paper position. 


In the overflow routine, you may. print total dines, skip to home paper, and print 


‘page headings. To branch back to the point in the program where processing 


would have continued (if overflow hadn’t occurred) you may use the address in 
register 14. If imperative macros (CNTRL, PUT) are issued in the overflow routine, 
you should store eae 14 before peeing the macro and restore it after the 
instruction is executed. ; : 


If overflow is detected during the issuance..of_ a CNTRL macro, control will be 
transferred to your overflow routine. os a 


PRINTOV=YES : | . 
Specifies that the PRTOV imperative macroinstruction will be ised in the 
program to control overflow detection and actions... : sae 


To use the forms overflow features, you must load the proper forms overflow 


- code in the. VFB for the 0770, 0776, 0768, and 0773. printers. If the PRTOV 


imperative macroinstructions are to be used with the 0770 printer, each code 


_required must be loaded in. the VFB. The.VFB is loaded through job control 


statements. The 0768 printer also :requires.a paper tape loop which must agree 
with the VFB statement. 


OS/3 data management will execute one user-issued CNTRL or PUT: macroinstruction 
after the immediate CNTRL or PUT instruction on which forms overflow was detected. 
If the imperative macro issued after the macro on which overflow .was: detected 
results in a forms advance to a aK eede (WEB. or paper tape eases your overflow 
options will not be. executed. ° ioe” 2 
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Keyword Parameter RECFORM: ~ 


One of the horowng three options describing the record format should be specified: 





. Fixed- fenath records for print files are assumed md the peace 1OCS when 
= this Reyiverd parameter: is ‘omitted. 


- RECFORM= UNDEF 
Used for undefined records. You must specify the RECSIZE keyword 
parameter when this format is used’ and enter. the size of each record into 
the RECSIZE togiste! Borers ieuine each nvr: macroinstruction.. See Figure 
c= : 


RECFORM=VARUNB at 
Used for variable-length, unblocked recordsn: 


Before issuing a PUT macroinstruction; you must include ‘a valid record length value 
(a binary number) in the record. This record length, inserted into the first two bytes of 
the 4-byte record size field, must include the control character, if PerOv eee. as well as 
four eyes for the Record size field ae Pee riguie eee = : 


Rayword pdeainetek RECSIZE: 


“'REGSIZE{(r) : mf b ake = Be 
For output files: with undefined recone format, epseities: the- number 2 through 
12) of the general register that holds the size-of the output record. If SAVEAREA 
is ‘specified, register 13 may be used as the RECSIZE° register. The record size 
’“must: ‘be:entered into the -géeneral register | before the PUT ‘Macroinstruction is 
issued. eas 


Keyword Parameter SAVAREA:. 


“SAVAREA=symbol_ 
If you have a program written 46 a SPERRY UNIVAC 9200/9300 Bye or 
similar system (in which register 13 was used), you'may convert the program to 
run under OS/3 by adding a 72-byte labeled save area (aligned on a full-word 
boundary) by adding this keyword parameter. 


This keyword parameter should be specified by you for each DTF in a program. Only 
one register save area is needed per program. Refer to 1.4 for the content of this 
area. 


If this keyword is not present in a DTF, logical |OCS will assume that register 13 has 
been loaded with the address of a 72-byte save area, aligned on a full-word boundary. 
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Keyword Parameter UCS: 


This keyword parameter is specified to determine whether character mismatches are 
to be ignored or not. A mismatch occurs whenever the printer attempts to print a bit 
configuration’ which’ is not present in the printer’s load code buffer: This: parameter 
has two formats: | | 





Character mismatches are ignored by the program. All unprintable 
characters are printed as the nonprinting code (NP) in the load code buffer. 
When the standard load code is used, a blank (4016) is printed, 


uCcSs= ON pean grey oe oo : 
The operator is notified of character fiseneiches: lf an error routine has 
been provided, control will be transferred to that routine and the registers 
- restored. If no error routine has been provided, a message will be issued 
and control will return to the program as if no error had occurred. 


Keyword Parameter WORKA: Sete ed Re 24. at ame a 


WORKA=YES | 
Specifies a work area , for . preparation of Slip records. The address of the 
current work area must Be specified with each PUT - macroInSiucten. 


( The WORKA and IOREG keyword parameters are mutually | exclusive: if both are 
ed specified, the WORKA keyword parameter is.ignored and an error flag appears in the 
DTF listing. Best -efficiency is: obtained with either of the following combinations: 


IOAREA1, IOAREA2, and IOREG 
or - 
IOAREA1 and WORKA” 


Example: . 
‘LABEL . AOPERATIONA : ; : - OPERAND | . : | A 
Po rabiner Flue DEFINITION, | SAMPLE: | 
ry et ere eee | 
Stamp... | DrePr| toaReA=eRee 
E | LK STzZE=1 32,. 
E | RECEwIR =VAIRUNEG 
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Table 7—3. Summary of Keyword Parameters for DTFPR Macroinstruction - 












“OUTPUT 
File 


The maximum block size in bytes, 
it ie 


CTLCHR Device- -independent control characters 


ERROR symbolic label, —— Address of your unrecoverable error routine 
IOAREA1 symbolic label =e Address of output area 

















, Keyword Specifications Remarks 









Specified if CNTRL macro instruction is issued to 
line spacing or skipping 
















1OAR EA2 _ Address of ‘alteenat output area’ 





: symbolic label 





General register (2 ‘hteuch 12) that ‘contains the 
address of the current record each time a PUT is 
issued. Register 13 may be used when SAVAREA 
keyword parameter is used. — 


( hence register 





Specifies an optional file that has not been allocated 
by job control 





OPTION 





Number of lines (1 to 15) to be spaced 


PRINTOV 





“symbolic label Address of your overflow routine 


Specifies execution of PRTOV imperative macros in 
program 












For fixed-length records 






RECFORM* 









UNDEF ae a For undefined records : 
VARUNB ae For variable-length, unblocked records 


(r)=general register 


SAVAREA — symbolic label a a 
Character mismatches will be ignored. 


aa Operator is notified of character mismatches. 





RECSIZE General register (2 through 13) that contains the 


length of each record when RECFORM=UNDEF 



















Specifies 72-byte register save area 





seeenioe 
oR Required 

Xx Optional 

Y One option required 





Value assumed if keyword is not specified 
* Parameter may be changed on DD job control statement 
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a 7.4. IMPERATIVE MACROINSTRUCTIONS 


There are five imperative macroinstructions available to you for processing SAM printer 


files: 
Macroinstruction Use 
OPEN File control 
PUT Record processi ng 


CNTRL ~~ File control?) 

PRTOV =° ~~ File control — bail | 

CLOSE File control. 

The following paragraphs describe the macroinstructions and their related parameters in 
detail and provide you with coding examples and explanations, when required, to clarify 
use. 
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7.4.1. Open a Printer File (OPEN) 
Function: 


Before a file can be accessed by the logical |OCS, an OPEN macroinstruction is 
issued. The transient routine called by the OPEN macroinstruction performs: certain 
validation checks and initiates file processing. A check is made to determine if. all the 
necessary keyword parameters defining the file have been supplied. The device 

i allocation performed by the job control program is determined, and the 1/O register is 
-. set up if one is specified. bee ee! st eR 


Format: 






A OPERATION A OPERAND 






filename-1 [,...,filename-n] 
‘" ) 


1 





aa 


Positional Parameter 1: 


filename 
Is the label of the corresponding DTF macroinstruction in the program. The 
filename may have a maximum of seven characters. The maximum number of 
filenames is 16. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the declarative 
macroinstruction. 


Examples: 


LABEL AOPERATIONA OPERAND A 
16 


1 

YeMels 1s | BREN | RNT1,PRNTZ 
Peweunen 
Zoi ti | A | ly Pre 
DMOZ 1.1 | z 


t) 
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1. Open printer files labeled PRNT1 and PRNT2. 


2. Open printer file labeled PRNT4. 


7-17 
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7.4.2. Output a Record (PUT) 


Function: 


The PUT macroinstruction delivers an output record to the logical IOCS in either an 
output area or a work area you have specified. This output record could be a line to 
be printed or, if the record comprises only control characters, could cause carriage 


movement alone. 


Format: 









OPERAND 
filename , ( workarea 
(1) 0 
1 0 


Positional Parameter 1: 






A OPERATION A 





LABEL 





filename 
Is the label of the corresponding DTF macroinstruction in the program. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the declarative 


macroinstruction. 
Positional Parameter 2: 


workarea 
Is the label of the work area from which the record may be obtained. 


(0) or O 
Indicates that register O has been preloaded with the address of the work area. 


If omitted, indicates that you have chosen processing either by means of a register 
(IOREG keyword parameter) or by directly accessing the data relative to the name of 


the I/O area. 


NOTE: 
When the work area is specified, the keyword parameter WORKA=YES must be present in 
the DIF statement. 
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Examples: 


LABEL AOPERATIONA OPERAND A 
6 


1 10 1 
Hota. | pot | PRAT. 

2} viii. | Pur, , | PRAT ZWwoeRKI 
Poti | ba, | lo worK2 
3}... 11) | Put | PRNTHICO 


Print a line, or space the paper. The record is located in an output area. The file 
characteristics are contained in the DTF table labeled PRNT1. 


> 


ob 


2. Move the record in the work area WORK1 to an output area and print, space 
paper, or both. 
3. Move a record from the work area whose address is stored in register O and 


print, space paper, or both. 
Programming Considerations: 


When WORKA=YES is used, a work area must be specified with each PUT 
macroinstruction. When only one I/O area is specified, you may move the records to 
be printed directly into the 1/O area. If you specify two |/O areas, you must use the 
1/O register (IOREG keyword parameter) to move records to be printed into one of the 
1/O areas before issuing each PUT macroinstruction. 


When printing variable-length, unblocked records, you must place the record length 
(as a binary value) in the first two bytes of the record size field. Undefined-length 
records require that you place the record length in the required register (specified by 
the RECSIZE keyword parameter) before issuing each PUT macro instruction. 


When you want to use control characters to position the form only (no printing) for 
variable-length, unblocked, or undefined record formats, you can indicate that the 
record contains no characters to be printed. 


When you are printing records in undefined or variable, unblocked format, printer 
SAM checks whether the number of columns being printed is greater than zero every 
time. If you try to print zero columns, data management normally issues error 
message DM18 (RECORD SIZE INVALID), sets the record size invalid error flag (byte 
O, bit 7) in filenameC, and branches to your error routine. Refer to Appendix B. 


However, this error processing does not take place when you are performing an 
advance-only operation using control characters; you may then indicate that there is 
no data to be printed. With either undefined or variable, unblocked records, you must 
place the record size in either the RECSIZE register or in the record size field in the 
record before issuing each PUT macro. To indicate that you have no data to be printed 
when your records are variable, unblocked, you may place a record size of five bytes 
in the record size field — provided that you limit this to advance-only operations. 
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When you are printing a record containing an odd number of characters to be’printed, = 
data management places a nonprinting character in the I/O area after the last byte of ~ 
user-Supplied data. 


UP-8068 Rev. 4" SPERRY UNIVAC OS/3 7) ee 
BASIC: DATA MANAGEMENT: 


~ CNTRL 


7.4.3. Control Printer Forms (CNTRL) 
Function: 


~The CNTRL macroinstruction controls printer forms spacing and skipping. Forms 
_.motion can.occur before, after, or both before and after a line is. printed... | 


Format: 








A OPERATION A — - OPERAND ~~ 


(filename) , {sk} Lm] Lal. 
(1) SP f 









te 


Positional Parameter 1: 


fe 


—~ filename ey, Pe EL | , cee oes 
wd Is the label of ne senescanding DTF MAGE CIS HMCNOn in | the programm: 


ot, 
en 


(1) or 1 


“Indicates that: register 1 has been Broloaded * with the address of the declarative 
. ‘Macroinstruction. . 


Positional Parameter ‘2 


Sk YS Eig 
Indicates that forms skipping is desired. 


SP 
Indicates that forms spacing is. desired. .. 


Positional Parameter 3: 


Specifies either the: number of lines (O through 15) for immediate spacing, or the 
channel code (1 through 15) for immediate skipping. The PUT macro performs 
spacing after printing. The number of lines spaced is determined by the PRAD 
keyword parameter (default causes advance of one line). Immediate CNTRL 
spacing is in addition to any spacing performed on a previous PUT 
macroinstruction. It should be noted that forms overflow processing can be 
er initiated after CNTRL processing (immediate or delayed) is performed. 


UP-8068 Rev. 4 . SPERRY UNIVAC OS/3 7-22: 
BASIC DATA: MANAGEMENT. 


‘Positional Parameter 4: 


n 
Specifies either the number of lines (O through 15) for delayed spacing, or the 
channel code (1 through 15) for delayed Skipping. 

Examples: 

LABEL cena HOn a _. OPERAND~  * pa ere 


Leer ee TZ, SP i913. 5 
Foti. | Por, | Prone, work 
2MoS 11. | RNTRL| PRONTIZ, SKIT yt 
orb | ote, PRET 2 WweR Ker er ba 
s[ | wwrss| Pears, pip Ti ss ten 


1. Space three lines ere printing the next line in file PRINT2 and five lines after 
printing the next line. 





2. Skip to the home paper position. 


3. After printing the next line, apt to ty home paper position. Se wee 


Programming Considerations: 


_.Because of differences. between the.,0770, 0773, 0776, 0778, and 0768 printers, 
substitutions have to be made for some skip codes on each. type of printer.. Table 7—4 
lists these substitutions. On the O768 printer, data management accomplishes 
spacing greater than three lines by issuing multiple 1/0 commands.- If you issue 
several control commands in succession, specifying delayed spacing or skipping, only 
the last delayed spacing or SIPPING enter is executed. 


Table 7—4. Device Skip Code Table (Part 1 of 2) 


Printer Code Substitution 
0773 and . 
0778 0770 0768 


(OVE EPS 3 | -Code 12(OV) | ° Chan.9 (OV): Code: 12 (OV): 
PP odie _ fe NoteGn; a, 4 pogo oa gy 
Note6 ... 


Skip to code n,m 
nymMm= 


| “Note 2— ~ Chan 15 (Note 4).| .Code.7 (HP) Note 2 
Code 1(OV)| Note5(OV) | u ~ Code 12 (OV): co 


ay i 
2 
3 
4 
5: 
6. 
7 
8 
a) 
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Table 7—4. Device Skip Code Table (Part 2 of 2) 


Printer Code Substitution 
0773 and 
0778 er ee 076 















































Code 3 

Code 4 ~ he fee ; : 

Code 1(OV)| Note 5 (OV) Chan 9 (OV) Code 12 (OV) 
Code 5 
Code 7 (HP) Code 7 (HP) Chan 15 (Note 4) Code 7 (HP) 


Code 7 (HP) | Code 7 (HP) Chan 15 (Note 4) Code 7 (HP) 


LEGEND: 


OV... Overflow. code or channel 


HP Home paper code 

NOTES: 

1. A blank in the code substitution column indicates that no substitution is made; data management skips to the code 
you have specified. 

2. Code 7 must be used as the home paper code on the 0770 and 0776 printers. 

3. A skip to code 7 control causes a skip to the home paper code on all printers. On the 0768 printer, the skip is to 
channel 14: or 15 (skip to channel 15 is:issued to the printer). On the 0768 printer, the home paper code used on the 
tape loop sets the number of lines printed per inch. Channel 14 results in 6 lines/inch line spacing and channel 15 
results in 8 lines/inch spacing. 

4. — Askip tochannel 15 issued to the 0768 printer. causes an advance to the home paper position, siti of gietiee 
channel 14 or 15 is punched in the paper-tape forms control loop. ns 

5. Code 12 is the primary forms overflow control code for the 0770 printer. Code 9 can also be detected as forms 
overflow code, using the PRTOV macro. If the PRTOV macro is not used, however, code 12:should be used'as overflow 
code, and code 9 should not be placed in the VFB. 

6. Data management. accomplishes spacing greater than three lines on the 0768 printer by issuing a number of 1/0 
commands. If the ‘user issues several ‘control commands: in: succession, specifying delayed: spacing ‘or skipping, only 
the last delayed spacing or skipping option is executed. 

7. 


For the 0768 printer, the software (physical IOCS) provides codes 2 and 3. . 
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PRTOV 


7.4.4. Print Overflow Action (PRTOV) .  . 


The PRTOV macroinstruction species the action to be taken when a forms overflow 
condition occurs. 


Format: 








LABEL A OPERATION A OPERAND 


| | ont 7 
0 
















| [is 


Positional Parameter 1: 


_ filename : 7 
“Is ne label of the corresponding DIF macroinstruction in the program. 


Indicates: that register 1: has een preieecer we the ade of hg ‘declarative 
macroinstruction. 
Positional Parameter 2:..-.. . 
9 


"Indicates that forms overflow. is..to-be indicated, by channel-9..- 





Indicates that forms overflow is to be indicated by channel 12 (0770 printer only). 


Positional parameter 2 is ignored for all printers except the 0770 printer. If omitted, 
channel 9 is assumed for the 0768 printer, and channel 1 is assumed for the 0773 
and 0778 printers. Channel 1 is the only overflow code recognized by the 0773 and 
0778 printers. Channel 12 is the only overflow code recognized by the 0776 printer. 


Positional Parameter 3: 


overflowname 


Is the label of your overflow routine. When overflow occurs and this option is 
specified, the logical I|OCS transfers control to this address. 
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(0) or O | adh 
Indicates that register" : has been epiclondedt with the address of your overflow 
_ routine. .. a : BN A = R Autth why 


“AE: omitted, aha! ieee locs provides an automatic ¢ skip to home paper in: ‘the paper 
tape loop. eee ae iy oe : ; 


Examples: 


LABEL ‘AGPERATIONA Nee Gi Bale OPERAND on | ee he 


prom Pom [pe WRKAL. 


ieee ea Et. OVE ILO. 


fou FE SP, — 





PIR.T ELLE, : ae 
fj eeeveren renee WRK A 
| leerevl leree29 1. 








: PIR TOM IF; Saray ae OVELOS, . 
"Piao. Penal aes, SPraisiZ 
a [i panel ives, q 


Wee an. ovedion: Senditian, ‘occurred on a ‘previous PUT. -or jiraeciats CNTRL 
. -Macroinstruction. execution on file. FILE1, SpIAney to routine OVFLO. Overflow 
codes detected are: Loe nape! - Bot Blan 





0773 printer — code 1 
0770 printer — code 12 
0768 printer — code 9 
0776 printer — code 12 
0778 printer — code 1 


2. If an immediate overflow condition occurred on a previous PUT or immediate 
CNTRL macroinstruction execution issued on FILE1, skip to home paper position. 


(Lines 3 and 4 of the example show selective overflow detection, which is possible 
only on the 0770 printer.) 


3. If an overflow code 9 was detected on a previous PUT or immediate CNTRL 
macroinstruction execution, skip to the home paper position. 


4. If an overflow code 12 (0770 printer only) was detected on a previous PUT or 
immediate CNTRL macroinstruction execution, branch to routine OVFLOB. 


5. If an overflow code is detected, a skip to home paper position will occur. 


UP-8068 Rev. 4 SPERRY UNIVAC O0S/3 7-26 5 
BASIC DATA MANAGEMENT .. 


scounnnng mousiaeiatens: 


When you use one PRTOV mactonsiracton in your program, you must apecity the 
PRINTOV=YES keyword parameter in the DTF macroinstruction for the file. The 
PRTOV macroinstruction. can be used with the 0770 printer to. Sleeve check -for a 
code 9 or code 12 forms overflow condition. ee! 


When the PRTOV macroinstruction is used, the logical |OCS performs either a skip to 
the home paper channel or a branch to your forms overflow routine when a forms 
overflow condition is detected on the preceding print or space command. The forms 
overflow code is not recognized during a ‘Skip operation. 


-OS/3 data management executes oné user-issued CNTRL or PUT macroinstruction 
after the immediate CNTRL or PUT instruction on which forms overflow is detected. If 
the imperative macro issued after the macro on which overflow was detected results 
in a forms advance to a skip code (VFB or paper tape code), your overflow options will 
not be executed. 


The — PRTOV macroinstruction may be issued: after’ each CNTRL or PUT 
macroinstruction, or, it can be: issued after. only «a PUT macroinstruction. It is also 
permissible to issue a a CNIRE, PUT, PRTOV macroinstruction sequenice. 


If an seaniont routine is epecitiod: the printer carriage is not t automatically restored to 
the home paper position. | ae ee) es _ 
The address of the instruction after the PUT macroinstruction, which detected the 
overflow condition, is stored in register 14. If imperative macroinstructions are issued 
in your overflow routine, register 14:should be stored peer issuing the i instruction, 
and restored after execution of the instruction. 
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~ CLOSE 


7.4.5. , Close a. Printer File (CLOSE) 


Function:. 
The CLOSE macroinstruction. is issued when all the data ina file has been processed. 
This macroinstruction calls a transient routine which checks for errors that may have 
occurred in the final output operation and then prevents further access to the file. 


Format: | 







A OPERATION A OPERAND 





filename-1 [,.. .,filename- n] 


(1) 
ja 
FALL 


Positional Parameters: gee 


filename 
Is the label of the corresponding DTF macroinstruction ‘in your program. The 
maximum number of filenames is 16. 

(1) or 1 
Indicates that register 1 has been. PISionneds with the address of the declarative 
-macroinstruction. m by OP ges cae So . 


*ALL 
Specifies that all files currently open in the job step are to be closed. 


Examples: 


LABEL AOPERATIONA OPERAND A 
16 


1 
joma7. 11. | Lege| PRNT2,PRNT 
ear eee ra 


2 eeewenra eee PRINT 
DMGS 1. | eLesel |O1) 


1. Close print files labeled PRNT2 and PRNT4. 


2. Close print file labeled PRNT1. 
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7.5. ERROR AND EXCEPTION HANDLING a 


7.5.1. FilenameC 


When certain errors or exceptions to file processing performance ‘are: detected by OS/3 
data management, it will make appropriate entries in specific fields of the DTF file table, 
which your program may address in order to learn of these conditions and take the proper 
course of action on regaining control. One such field in the DTFPR file table is filenameC, 
al -byte field which you may access by concatenating the character C to your 7- character 
le name and using the assembler language test-under- mask (TM): instruction. 


Bee: to Appendix B for the meanings of the bits in filenameC of the DTFPR file table 
which are set to binary 1 by OS/3 data management for certain error and exception 
conditions. 


7.5.2. Truncation of Print Line 


When OS/3 data management detects that the execution of a PUT macroinstruction has 
resulted in the printing of a truncated line, it sets the /ine truncated flag in filenameC (bit 
O, byte O) (Appendix B). However, it does not pass control to your error routine until after 
the printer file has been closed, by which time other truncated lines may have also been 
printed. Depending on your requirements, you may find it useful in your program to test 
for setting of the /ine truncated bit after each execution of the PUT macro and provide for 4 : 
a flag character to be printed with the next line to speed visual location of all truncation ~ 
errors on your pees 


7.6. SAMPLE PROGRAM 


The following sample program, constricted to illustrate a typical use of the OS/3 data 
management printer system in a BAL program, also indicates where to place: the OS/3 job 
control statements needed to implement it. 
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10. ‘ISAM Formats and File Conventions 


10.1. GENERAL 


The indexed sequential access method (ISAM), one of the five methods that OS/3 data 
management provides for handling your disk files, may be used with all available disk 
subsystems. These are: SPERRY UNIVAC 8411 Disk Subsystem; SPERRY UNIVAC 8414 
Disk Subsystem; SPERRY UNIVAC 8415 Disk Subsystem; SPERRY UNIVAC 8416 Disk 
Subsystem; SPERRY UNIVAC 8418 Disk Subsystem; SPERRY UNIVAC 8424 Disk 
Subsystem; SPERRY UNIVAC™ 8425 ‘Disk Subsystem; SPERRY UNIVAC 8430 Disk 
Subsystem; and SPERRY UNIVAC, 8433. Disk Subsystem. The 8415, 8416, and 8418 disk 
subsystems are fixed-sector disks; on which data records are written in fixed physical 
sectors of 256-byte lengths. All data transfers must be multiples of this length. The others 
are variable-sector disks. Each OS/3 data management processing module handles all disk 
types, in order to give you as much device-independence.as possible. You seldom need to 
be concerned with most of the details of the way these disk subsystems operate. Those 


_ functional characteristics you will find useful, however, are presented in Appendix A. 
ISAM does not support the 8413 diskette.” . oo 


ISAM is the only method that gives you the capability of building a hierarchy of index 
blocks to support a search of your files by key; its search-by-key function allows you 
to perform random retrieval in a relatively short — time. In OS/3 ISAM, a key is a 
character string that you specify within each logical record, to uniquely identify that 


_record. Its minimum length is 3 bytes; its maximum is 253. One restriction on the 


content of keys is that no byte of any key may contain the hexadecimal value FF 


(11111111 in binary). A key that contains FF, may produce erratic results during 
‘retrieval by key. Another restriction on the content of keys is that you may not have 


a key constituted entirely of binary O's; this key is reserved for a dummy record that 
data management creates and inserts at the start of every ISAM file. The reasons for 
these restrictions on key size and content are developed later in the manual. 


‘As in other OS/3 data management systems, a logical record is simply what you tell 


data management it is — a character string that you define and that data 
management handles as an entity in storage and retrieval: 
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To use ISAM's search-by-key function, you must first present your records serially with 
keys and load them sequentially onto disk. You present your records to data management, 
unblocked and one at a time, in ascending order of these keys. Data management blocks 
your initial records into an area of your file, termed the prime data area, and builds the 
‘index structure used to effect random retrieval by key. After initially creating your ISAM 
file, you may add new records, presented in any key order. OS/3 ISAM does not place 
these in the prime data area; it places your new records in an overflow area of your file 
and logically chains them to the proper points in the pre-existing series of records, 
maintaining the effect of one long, orderly series. (Other ISAM systems insert new records 
on the original prime data tracks, and existing records are pushed down; OS/3 avoids this 
inefficient process.) 


You may retrieve and update your records in any of the following ways: 

# sequentially, progressing from any record toward the end of the Sériaa: 
i randomly, by presenting a key; or 

- randomly, by presenting a relative dddress. | 


. Another significant point af difference between this and lie similar access methods is 
‘that OS/3 ISAM also allows you the option of side-stepping. the formation of the ISAM 
index. When you do so, your records need not be keyed, and the key-based functions of 
‘the ISAM repertoire are inoperative, yet you retain. full abilities for sequential access, 
direct access, and inserting records: 


The advantages of using OS/3 ISAM without an index (ASAM) are these: 


= Although your ASAM file is, in effect, a sequential file, under ISAM you have direct 
addressing capabilities that are not available to you under the OS/3 sequential 
access. method (SAM). 


2 Your ability to add. records to an ISAM file gives you the SapeD Ny of building a 
header-trailer file and forming trailers dynamically. 


~ Another advantage of 0S/3 ISAM “over earlier systems is that a program referencing 
several disk files, one of which is an ISAM file with index, may employ the same 
_ processing module to reference the other files; that is, you may use an OS/3 ISAM 
~module to process ASAM files sequentially or directly. | 


Usually, an OS/3 ISAM file will be one. of several files occupying the same disk pack. 
Every pack is provided with a volume table of contents (VTOC), which facilitates system 
control of disk space and file location. (The VTOC and the system standard disk labels used 
in common by all OS/3 data management access methods are described in Appendix D of 
‘this manual. But it is worth noting at this. point. that ISAM does not support user labels for 
disk files.) 
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10.2. ISAM FILE ORGANIZATION 


When you are using the index- building feature of OS/3 ISAM, your file space on disk is 
divided into two parts: the index area and the data area. The index area is devoted. entirely 
to 256- bye index blocks, formatted for hardware search. — 


An ISAM key dearchy which always starts at the beginning of the top index, executes a 
disk search and retrieves a block that contains an entry pointing to another index track. 
When this is searched, a second index block is read; the second block contains an entry 
pointing to the desired data block in the data area. (In some cases, however, when the size 
of your keys and the size of your file are unusually large, data management will need to 
make one additional index-track search to reach this data-pointer level in the index. A 
number of measures, developed later in some detail, will help you minimize this index- 
searching overhead; for the moment, however, remember that you do have some options.) 


The index area is formatted to permit hardware search, equal/high. By ““‘hardware search, 
equal/high”, we mean that the disk subsystem itself, once provided with your key and 
positioned to the index track by data management, tests each index block as it comes 
under the head to see whether the key on disk is equal to or greater than the key 
presented to it. Key comparisons are made within the disk control unit and do not involve 
transmission of key information to main storage. Only when a hit is made does the 
physical input/output control system (IOCS) return the index block to main storage, where 
data management examines it to decide which block to search for next. No read from your 
data area on disk is performed until a hit in the block index has pointed to the data block 
sought. When this data block is brought-into main storage, data management searches it 
there for the logical record you have requested. 


This exploitation of the hardware search capability of the disk subsystems makes for 
speed, but a hardware search of the entire index can be avoided when you place part of it 
in main storage. This point is developed further in 10.2.4 and 10.2.5. See also the 
discussion of the INDAREA keyword parameter (11.4. 5). 


The data area of your file contains only data bocks, which are not forndiied for hapaware 
search, and cylinder overflow control records (COCR). The data blocks are either prime 
data blocks filled during your initial file load, or overflow data blocks, filled by your 
subsequent additions to the file. These blocks are identical in form; the only difference is 
their location, in either the prime data area or the overflow area of the cylinder. You will 
specify the percentage of each cylinder of your file that. data management is to reserve for 
overflow when you first design and describe the file, using a certain keyword parameter in 
the declarative macro that defines it to OS/3 ISAM. Figure 10—1 shows the two partitions 
of an indexed OS/3 ISAM file. 
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ISAM Index Partition 














4 tracks 
(2 tracks 
on. 8416 
and 8418 
disks) - -256-byte index 
blocks, hardware- 
_ Searchable. 
- ISAM Data Partition 
. prime data area . 
cs ree a user-specified 
data blocks, 
not hardware- 
er | searchable. 
| overflow data : 
area : 
LEGEND: 


COCR Cylinder overflow control record; written by data management in last block of: -eylinder and “eints to the. location 
of remaining overflow space on this cylinder. 


Vee 


Supplied by OS/3 data management. 





[| , Data supplied by you; you “alse specify to 0s/3 data management the percentage of cylinder area that is to be 
~ "assigned to réceive overflow records. The preekpelnt between prime and overflow need not fall at a track 


boundary. | 
Figure 10—1.. The Two Partitions of an Indexed OS/3' ISAM File: Cylinder Formats of the Index Partition and the Data Partition 


~ 
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Because it is unlikely that you will use the overflow areas at the same rate.¥in all your 


cylinders, some may be.filled while others are hardly. touched; this is where the COCR 
comes in. When a cylinder’s overflow area can take no more, OS/3 ISAM will place 
records ordinarily destined for that cylinder onto other cylinders having overflow space 
available. The COCR is in the last data block of the cylinder, and i is used to keep track of 
available overflow space. 


During its original loading of your file into data blocks on disk, data management inserts a 
5-byte data pointer field after each prime data record. It will use these fields’ later, 
whenever you present new records for insertion, to set up the required logical sequence 
and to keep it current. (You have a use for this data pointer, too, for ‘retrieval of records 
without keys; this point is developed later.) 


New records are never actually /nserted, although a rewritten record, which is an update 
of a record already on disk, is written back into the location of the original. As Stated 
previously, data management: places new records in the overflow area and chains them 
into, logical sequence. All records remain at the locations where they were originally 
placed, making it easy for you to point to the records of one ISAM file from the records of 
some other file. Because an updated record is always written back to its original spot, you 
must never alter either the original key or record.Jength of a record when.you update it. 


The most significant three bytes of the 5-byte data pointer contain the record’s block 
number, relative to the start of the data area; its least significant two bytes’ contain’ the 
byte position of the record within this block. You may address all ISAM data records 
directly by their 5-byte relative addresses of this format, which you will express in binary 
form. 


10.2.1. ISAM Record Formats 


Your OS/3 ISAM file may contain either fixed-length or variable-length blocked records — 
this is a difference between OS/3 and some earlier systems, which allowed only fixed 
record engine: You present your records one by one, and ISAM blocks them.. 


If your petotes are variable: “you must insert into the. jesding’t two bias of every logical 
record the length of that particular record in binary form. Fixed records do not require this 
2-byte field. (It is worth noting, if you are familiar with other systems using a 4-byte record 
length field at the head of each variable record and reserving two of these bytes for 
system use, that OS/3 ISAM does not do so — only two bytes are used for record length; 
the rest et the record is yours): 


When you submit keyed records to: 0S/3 ISAM which you must do when you are using 
the index feature and may do even when you are not), all logical records in the file must 
have keys. Each key must be unique in content, equal in size to the other keys, and must 
be located at the same distance from the start of its record. As noted before, a key may 
always be embedded in a record; its length may not be less than 3 bytes nor exceed 253 
bytes. 


Figures 10—2 and 10—3 show the formats of OS/3 ISAM logical records, keyed and 
unkeyed. 
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Key at Head of Record ~ 





Key Internal to Record 





Without Key. 





LEGEND: 

K Record key. All keys in a keyed file must have the same length; each record in a keyed file must have one (and only 
one) unique key; and the starting location of the key must be the same in each record. You specify the length of the 
key with the KEYLEN keyword parameter; minimum length. is 3 bytes, maximum is 253. 

L Key location. The starting location of ihe key must be the same in each record. You may specify the ‘number of bytes 
of data preceding the key with the KEYLOC Bevyond parameter. If keyword is omitted, ISAM assumes the key starts in 
the first byte of a-fixed record. : 


D __—cData nortan of your logical record 


R Length of logical fixed-length record (key plus data). You specify this length, measured in bytes, with the RECSIZE 
keyword parameter, it must never exceed the value of data block size, less seven bytes. 


Figure 10—2. Fixed-Length ISAM Records with and without Keys 
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Key at Head of Record 





Key Internal to Record 





Without Key 
rl data 
F a ace eee D 
V 

LEGEND: 

F A 2-byte record length field. You insert the length of each variable record into this field in binary; the length includes 
this 2-byte field and is equivalent to V in this figure. 

D Data portion of your logical record 

Vv Length of a variable record. Includes key plus data, plus two bytes for the record length field. You never specify this 
length with a keyword parameter but place it in the leading two bytes of each variable record (in the field represented 
by F in this figure). 

K Record key. All keys in a keyed file must have the same length; each record in a keyed file must have one (and only 
one) unique key; and the starting location of the key must be the same in each record. Minimum key length is 3 bytes; 
the maximum is 253. You specify the length of the key with the KEYLEN keyword parameter. 

L 


Key location. The starting location of the key must be the same in each record. You may specify the number of bytes 
that precede the key with the KEYLOC keyword parameter. If you omit the keyword, ISAM assumes the key begins in 
the third byte of a variable record. 


Figure 10—3. Variable-Length ISAM Records with and without Keys 
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10.2.2. ISAM Data Block Format 


When OS/3 ISAM writes your records to the disk, it blocks them into data blocks, the size 
of which you specify. (This data block length is the same as the length of your I/O area, or 
data buffer, and may contain unused space, for reasons discussed later.) All data blocks 
begin with a 2-byte field called the b/ock header, which states the number of bytes in the 
block that are currently occupied. Because every logical record is accompanied by the 5- 
byte data pointer just mentioned, the maximum size of any logical record is thereby limited 
to data block size minus seven bytes. And, because the effective data length of a variable 
record is further reduced by its own 2-byte record length field, the number of bytes of data 
that your longest variable record may contain is no more than data block size less nine 
bytes. 


Although you should use as large a block as you can afford to have in main storage, data 
buffer size is not entirely up to you. It may never be less than 256 bytes, for example, 
because this is the length of the index blocks, and ISAM handles these through the I/O 
buffer (whose length you specify when you specify data block size to data management). 
Furthermore, you should set data block size at some multiple of 256 bytes if you are using 
the fixed-sector 8415, 8416, or 8418 disks at your installation. If you do not specify a 
multiple of 256 bytes, ISAM increases your specification to the next higher multiple. If 
your data block size is less than 256 bytes, then you must specify a BLKSIZE length of 256 
bytes or more. Finally, whether you are using this or the variable-sector 8411, 8414, 
8424, 8425, 8430, or 8433 disks, the block size you specify must not Sxneee the track 
size for these devices: 


SPERRY UNIVAC Track Size, 
Disk Subsystem in Bytes 


8411 3625 
8414 7294 
8415 10,240 
8416 10,240 
8418 10,240 
8424 7294 
8425 7294 
— 8430 13,030 
8433 13,030 


Figure 10—4 illustrates the layout of two ISAM data blocks on disk, one containing two 
fixed-length records, and one containing two variable-length records. The legend relates 
the segments shown to various keyword parameters you will use in the DTFIS dec/arative 
macroinstruction to define your file to OS/3 ISAM. (The DTFIS macro and its keyword are 
described in detail in Section 11.) 


‘Note that aire 10—4 shows some unused space at the end of each data block. You 
should avoid this (if you can) when you specify data block size for a file containing fixed 

records, by ensuring that the sum of your logical record size, plus five bytes for the record 
pointer following each record, divides evenly into the block size — not forgetting that block 
size must always include the 2-byte block header field. 


On the other hand, it is generally not possible for you to avoid some unused space in the 
data block when your ISAM file contains variable records. 
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Fixed Records 





Variable Records 





LEGEND: 


B Block header, written by data management in.the buffer. This is always two bytes long and contains (in binary) 
the number of bytes in the data block which hold usable information. In the example shown, this figure would 
equal (I) minus (U); it includes the total space occupied by the records themselves and the 5-byte data pointers, | 
one of which follows each of the records. Because data management appends the block header in the buffer, 
and it is placed in the buffer with the block when it is retrieved, you must allow for this 2-byte header in 
calculating the data block size, which you specify with the BLKSIZE keyword parameter. However, it:is not 

-. moved to your record work area (the address of which you specify with the WORK 1 keyword parameter) where 
data managemens presents your records, one by one. 


K Record key. This may be internal to the record instead of being located (as shown) at the head of the 
record. All keys in a file must have the same length; each record in a keyed file must have one and 
only one unique key; and the starting location of the key must be the same in each record of the file. 
You specify the starting location of the key with the KEYLOC keyword parameter, and its length with 
the KEYLEN parameter; minimum key length is 3 bytes and maximum is 253. (When you present a key 
that you want ISAM to match by search you load it in an area of your program specified by the 
KEYARG keyword parameter.) 


D Data portion of your logical record 
F A 2-byte record length field of a variable record 


P Record pointer, a 5-byte divider which follows every record that data management writes into the data 
block. The record pointers are written by data management, but you must allow space for them in 
calculating your I/O area length, which you specify with the BLKSIZE keyword parameter. Data block 
size and I/O buffer size may differ; the buffer must be at least the size of the data blocks, but may be 
greater. The record pointer contains, in ‘binary, the block number. and byte position in that block of the 
next sequential logical record in the file, in the form rrrbb, where: rrr is the block number, relative to 
-the data partition; and bb is the displacement, measured in bytes, of the record into that block (a record 
preceded by 125 bytes will have a displacement value of 125). You will use this 5-byte “address” when 
you retrieve records directly, rather than by key. (This address is always returned to you by data 
management after each record is loaded or added to your file; it is your responsibility to access it and 
store it for later use, if you plan to use it. Data management piece. this 5- byte” value in the field’ of 
your DTF called filenameH.) 


Figure 10—4. Layout of ISAM Data Blocks (Prime or Overflow) on Disk Each Containing Two Logical Records (Part 7 of 2) 
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LEGEND (cont): 


U : Any unused space at the end of a data block. Usually unavoidable in data blocks containing variable-length 
2 records, this dead space may also occur in files of fixed records, if the sum of the logical record size (R) plus five 
bytes for the record pointer (P) does not divide evenly into (I), the data block size you specify. 


R Length of logical fixed-length record (key plus data). You specify this, measured in bytes, with the RECSIZE 
keyword parameter. This must never exceed the value of the data block size, /ess seven bytes. 


V Length of logical variable-length record (2-byte record length field, plus key, plus data). You never specify this 
length with a keyword parameter; you place it in the 2-byte record-length field at the head of each logical 
record. Like the length of a fixed record, it may never exceed the value of data block size, less seven bytes. 


| Length of I/O area, which you specify with the BLKSIZE keyword parameter. It includes the 2-byte block header 
: length, plus the record length of each logical record in the block, plus the 5-byte record pointer that must follow 
each record. It also includes such unused space as you have been unable to avoid. 


Figure 1 o—4. Layout of ISAM Data Blocks (Prime or Overflow) on Disk Each Containing Two Logical Records (Part 2 of 2) 


Figure 10—5 is a schematic diagram of OS/3 ISAM’s method of chaining records in 

logical sequence. The upper tier of records represents those placed into:the prime data 

area by an initial load of the file in ascending order of record keys (keys being represented 

by the numbers). After the initial load, the record pointer that follows each record 

contained the hexadecimal pattern FO AA AA AA AA, indicating that the next record in - 
physical sequence was also the next in logical sequence in the file. (The record pointer 

after the record whose key is 750 still points in this way to the start of the one whose key 
is 809, for example.) After the lower tier of four records was added (to the overflow area), é 
data management. rewrote some record pointers as necessary | to chain the new records oe 
into their logical sequence. The record | pointer following record 827 originally contained 

the pattern pointing to record 902, which is the next record in sequence in the original file 

and happens to be the first record in the next data block. After the addition of record 901, 

data management rewrote this to point to the new record; the new record pointer 


following 901 is now the one pointing to 902. 














Figure 10—5. Schematic Diagram of ISAM Records Chained into Logical yore after eee 
Records to the File (Part 1 of 2) 
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LEGEND: 


Noa bh Block header, a 2-byte field at the head of each physical data block. Written by data management to indicate the 
number of bytes in the block that are devoted to usable data. 


“rp Record pointer, a 5-byte field inserted by data management following each logical record written to a 
data block. Originally, after initial load, contains hexadecimal pattern FO AA AA AA AA, pointing to next 
sequential record in the file. Rewritten by data management as necessary to point to records “inserted” 
by addition after initial load. 


Logical records submitted by you in ascending order of keys. The top tier represents prime data records 
submitted by an initial load; the lower tier represents four records submitted by a subsequent operation, placed 
in overflow, and chained into logical sequence by OS/3 ISAM. 


fa 


Supplied by OS/3 ISAM 


yy 


N Unused space in physical data block 


Figure 10—5. Schematic Diagram of ISAM Records Chained into Logical Sequence after Adding 
Records to the File (Part 2 of 2) 


10.2.2.1. Calculating Space Requirements for the File 


To calculate the number of cylinders required for data in an ASAM or ISAM file, you may 
proceed as follows: 


1. Calculate r, the number of logical records per data block (r is an integer): 





(block size) — 2 bytes 
(average record size) + 5 bytes 





2. From this, calculate b, the number of Puig data blocks required for the initial ISAM 
load: 


number of records to be loaded 
r 


b= 


3. Then calculate d, the tota! number of data blocks (prime plus overflow): 


- 100 b 
100 — (percent overflow) 


4. Calculate the cylinder capacity of the disk subsystem you are using: 
cylinder capacity = (number of surfaces per disk unit) (track capacity) 


The number of surfaces and the track capacity for the various disk subsystems are 
shown in Table A-4. 


5. Calculate the number of data blocks of the desired size each cylinder can hold: 
number of data 


blocks each cylinder = 
can hold 


cylinder capacity 
block size 
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—> 6. Finally, convert d into Ca, the number of cylinders required for data: 


d 
Ca= (number of data blocks each cylinder can hold) 


10.2.3. ISAM Index Blocks 


The index area of your ISAM file is, as we stated previously, entirely devoted to 256-byte 
index blocks, which are written for you on the index tracks by OS/3 data management. 
The format of these blocks is shown in Figure 10—6; they contain keys and 3-byte 
-pointers to the prime data blocks and are hardware-searchable. 


ISAM Index Block on a Fixed-Sector 8416 Disc 





_ 256 bytes 


ISAM Index Block on a Variable-Sector Disc 





sum = 256 bytes 


LEGEND: 


HK High key of the block. 

PH _ Pointer following the high key of the block — points to next level below 
P A 3-byte pointer to next level below 

ZG 

Z Unused space in index block 


K,,Ko,...Kn are ascending keys, < HK 


Figure 10—6. Format of Full OS/3 ISAM Index Blocks 
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Note that all the entries are fixed-length and that the index block has no block header 
field. If the final block of an index level happens to be a full block, it will have the form 
shown in Figure 10—6, and the high key of the block will contain all 1 bits. If the final 
block is not full, its form will differ in that the top entry with a key of all 1 bits will be 
repeated between the last record pointer and the unused space. As a result, a scan of a 
final index block in main storage will search only valid information; there is no possibility 
of its running on into the spurious information contained in the unused space. 


Each scan of index blocks in main storage begins at the K, position. In the ordinary full 
block, the result may be a hit on or before Kn; if it is a miss, the search uses the PH 
pointer to locate the next index block to scan. 
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Note that, like the ISAM data blocks, the index blocks may also contain unused space if 
the sum of the key length (measured in bytes and uniform for every key in the file), plus 
three bytes for the track or block pointer that follows each key, does not divide evenly into 
256. If your keys are 40 bytes long, for example, you can fit only five of them (and their 
accompanying 3-byte pointers) into 256 bytes and will have 41 unusable bytes left over. If 
you are designing a file, therefore, and have some latitude in choice of key length, it is 
wiser not to establish it arbitrarily, but to choose a key length that will give you the least 
wasted space in the index blocks. Figure 10—7 recapitulates much of what has been 
discussed so far: it shows the layout of an index partition and a data partition of an 
indexed ISAM file as they appear on disk: 


256 bytes 











INDEX BLOCK ON 
FIXED SECTOR DISC 


UP TO FOUR 
INDEX TRACKS OF 
PARTITION TOP INDEX 
INDEX BLOCK 
ON VARIABLE 
SECTOR DISC 
9 FORMAT OF 
PRIME AND 
OVERFLOW 
BLOCKS 
DATA 
PARTITION 


Prime Data Blocks 


ee 






ts Overflow Blocks 








Figure 10—7. OS/3 ISAM File Structure (Part 1 of 2) 
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LEGEND: 
K Record key 
P Pointer 
bh Block header 
ui Logical record 
WN Unused space at block end 


COCR Cylinder overflow control record; written by data management 


System-supplied pointers, headers, and count fields on disk 


Figure 10—7. OS/3 ISAM File Structure (Part 2 of 2) 


10.2.4. Calculating Space for the ISAM Index Area 


You may calculate your disk space requirements for the block index of your ISAM file by 
the process shown below. Because the space needed to hold your index is inversely 
proportional to the size of your data blocks, you should favor larger over smaller data 
blocks when you design your file, to avoid excessive index space. 


To calculate the number of cylinders (C,;) that your block index will need, you start with 
your block size, the average size of your records (if they are variable), the total number of a 
records in your file, and the size of keys in the file. These are the five steps we suggest ( ) 
you take; they can, of course, be compressed into one calculation: = 


1. Calculate r, the number of logical records per data block (r is an integer, naturally): 


= blocksize — 2 
average record size + 5 


2. Calculate b, the number of prime data blocks you require: 


total number of records to be loaded 
r 





b= 


3. Calculate e, the number of entries data management will make per index block (e is 
also an integer): 


— 256 
keysize + 3 


4. The next calculation gives i, the number of index blocks you will have: 


b 
e 
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5. Dividing this by the number of index blocks each cylinder may hold (a constant 
depending on the disk subsystem) gives C,, the number of cylinders your block index 
will require: 


ee ee 
a number of index blocks per cylinder 


These are the numbers of 256-byte ISAM index blocks that each cylinder may hold on 
the disk subsystems used by OS/3: 


SPERRY UNIVAC Number of 256-byte 
Disk Subsystem Index Blocks per Cylinder 
8411 100 

84.14 340 

8415 fixed 120 

8415 removable 80 

8416 280 

8418 280 

8424 340 

8425 340 

8430 551 

8433 : 551 


The foregoing calculations hold good for the second level of your ISAM index: the block 
index. For a useful approximation of the disk occupied by the entire index (when there is 
no intermediate index), you need add only the number of tracks that ISAM sets aside for 
the first level, which is the top index: two tracks for an ISAM file residing on an 8415, 
8416, or 8418 fixed sector disk, and four tracks for the variable sector 8411, 8414, 8424, 
8425, 8430, and 8433 disks supported by OS/3. 


The calculation of the amount of disk space actually occupied by your top index (without 
the repetition pattern mentioned in 10.2.3) is more complex. Of course, you can readily - 
figure the maximums: 


Track Capacity 


Disk Subsystem Maximum Number in 256-byte Maximum Number 
on Which ISAM __ of Tracks for Top Index of Bytes for 
File Resides Top Index Blocks Top Index 
8411 4 10 | 10,240 
8414 4 17 17,408 
8415 2 40 20,480 
8416 2 40 20,480 
8418 2 40 20,480 
8424 4 17 17,408 
8425 4 17 17,408 
8430 4 29 29,696 
8433 4 29 29,696 
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However, these maximums are rarely reached in practice; few files require more than 3K 
bytes for the top index. 


The most convenient procedure for learning the size of the top index is to access 
filenameS after issuing the ENDFL imperative macro that terminates the initial file load or 
each subsequent extension of it (11.5.2.3). ISAM places the number of bytes required to 
hold the top index of a file in main storage in this 2-byte field, which is half-word aligned 
and addressed by concatenating the character ‘’S’’ to your 7-byte file name. This is the 
figure you need to know for subsequent random operations on your file, because you can 
improve the speed of your keyed search operations (for add and retrieval) by providing 
main aolage space for some or all of the top index. 


10.2.5. Loading the Top Index into Main Storage 


To speed random retrieval or record insertion operations in an ISAM file, you may specify 
that data management is to place as much as possible of your top index in the index buffer 
(INDAREA, 11.4.5) for subsequent search there. Doing so minimizes the hardware search 
of this part of your index on disk; if you can allow enough space in main storage for the 
entire top index, a search of it on disk is eliminated atoge teh Only top Index entries may 
be brought into main storage. : 


As explained in 11.4.5, when you specify random retrieval operations, or record insertion 
operations, or both, you may direct ISAM to bring your top index into main storage by 
proper specification of the INDAREA and INDSIZE keywords. 


When your ISAM file is first opened for random retrieval or record insertion, if you have 
specified that your top index is to be brought into main storage, the OPEN transient 
computes the number of top index blocks that can be held in a table of the size you have 
specified with the INDSIZE keyword, reads this number of top index blocks (commencing 
with the trailing block and working toward the start of the index), and transfers these 
blocks to the INDAREA buffer. Although the top index blocks are not reformatted, ISAM 
eliminates any unused space in each 256-byte index block. The appearance of your top 
index in main storage is then as depicted in Figure 10—8. Notice that the part of your top 
index that is in main storage always includes at least the /ast block, which contains the 
high key (hexadecimal FF). Including this key guarantees that an equal/high comparison 
will result when the index is searched in main storage. 


The search of the index in main storage is initiated by a READ, KEY; ADD; or WRITE, 
NEWKEY macro issued to the file. First, the search compares the key argument (KEYARG, 
11.4.9) to the low key of the top index segment in the INDAREA table. If the argument is 
equal to or greater than the low key of the INDAREA table, then a comparison is made 
against the high key of each block of the top index in the table until an equal/high 
comparison results. Then each entry in the block thus located is searched on an 
equal/high basis, to isolate the index entry that corresponds to the key argument. The 
search next turns to the block index on the disk (via the intermediate index, if one is 
present on disk) and from there to direct access of the prime data block sought. 


oo 


Soca” 
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Top Index Block 1 “2 





Top Index Block 5 Top Index Block 6 


Corresponding INDAREA Index Table in Main Storage, 
Assuming INDSIZE Specification Accommodates Three Blocks: 
—-—_ Block 1 ——— >< Block 2 ———— 
4 be Fa K.. . 





“= (Block a a ipa tian mace Block 3 — | 
LEGEND: 
K Record key 


P 3-byte pointer to. next index level below 


_ Unused space in top index block on disc 





Figure 10—8. Blocks of an ISAM Top Index on Disk and Corresponding INDAREA Table in Main Storage 


- # 
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Referring again to Figure 10—8, consider that the KEYARG field contains the key 13.5. 
The search follows the following logic: 


1. Compare KEYARG (KA) to Kyo, low key of the INDAREA index table: KA > Kyo. 
Therefore continue search in table. 


2. Compare KA: K,2, high key of block 1: result low. 
a7 Compare KA: Kis, high key of block 2: result high. 


4. Therefore search block 2, each entry: result is hit on K,,. Search of INDAREA table in 
main storage is complete; P,, points to next lower level of index, on disk. 


On the other hand, if the key argument is lower than the low key of the INDAREA table, 
the search moves the disk, where a hardware search of the top index begins in the usual 
manner, as described in 10.2. The part of your top index that you have placed in main 
storage is not searched again on disk. 


10.3. ALTERNATE SEQUENTIAL ACCESS METHOD (ASAM) 


OS/3 ISAM provides the usual ISAM capabilities of retrieving sequentially or by key; and 
provides the additional capability of retrieving by address. The coding necessarily includes 
the simpler coding required for SAM processing and relative record DAM processing. 
Therefore, it was not difficult to provide handling for unkeyed sequential files wherein the 
index structure is omitted and keyed functions are avoided. This eletnate sequential 
access method is eened ASAM. 


Some of the reasons for using ASAM files are: 


1. A program is required to retrieve from a keyed file and from a sequential file. If these 
are specified respectively as ISAM and ASAM files, the same data management 
coding handles both. 


2. Direct addressing into an essentially sequential file is desired, and ASAM handling is 
found to fulfill the need. 


3. It is desired to insert new data between records of a previously formed file, and to 
retain direct access capabilities. The inserted data may be additional records of the 
same nature as the original records, or they may be addenda to the record from 
which they are chained. 


The important things to remember about ASAM files are these: 


# No index or index space is provided; hence records may not be retrieved by key 
search. 


# Records may be retrieved randomly (as in ISAM) by providing the record address that 
was returned to you at the time the record was placed in the file. You must make 
your own arrangements for retention of addresses; alternatively, you may calculate 

- addresses, if your records are of fixed size. In this case, remember that there is one 
dummy record at file start. 


SB, 
fos 


UP-8068 Rev. 4 | SPERRY UNIVAC OS/3. ~ 10-19 


BASIC DATA MANAGEMENT 


= Any block may be retrieved by providing the 3-byte number, followed by the 2-byte 
field containing binary 2 (the address of the first record of the block). 


i ‘Sedueitial retrieval is the same as in ISAM except that the SETL, KEY and SETLG, 


KEY imperatives cannot be used to Start the sequence. 


= If records are not to be added, you may specify zero overflow space. Nevertheless, the 
5-byte pointers will be appended to records. 


# It may be desirable to have prime records of one size and addenda of other sizes. 
Remember that all records must have variable record formats, if there is to be any 
variance in size. | 


# In order to add records, you must provide ASAM with the address of the record that is 
to be followed by the new record. 


=»  ASAM files will usually be defined as unkeyed. If keys are specified, ASAM will reject 
duplicate and out-of-sequence keys during LOAD. When such checking is necessary, 
you may save some coding by having ASAM do it. . 


# As in. ISAM, you must use the SETL and ESETL imperatives to start and end a 
sequential progression. While you are In sequential mode’ you may not perform 
random functions. 


Figure 10—9 shows the logical aspect of an ASAM file in which not more than one 
addendum record in overflow has been chained from the prime record to which it relates. 


Because you may logically insert new records at any point in the ASAM file, it is possible 

to subordinate or connect several addendum records in overflow to each prima data 

record. A file you may structure this way may be of more interest or use to you than one. 
based on the one-to-one relationship suggested so far. If you add your new records to 

overflow and provide ASAM with the address of the same prime data record for each of a 
group of, say, three records that you want related to it, these are chained in the sequence 

shown in Figure 10—10. The same chaining can be obtained by successive adds on three 

separate occasions — a point to remember, therefore, is that when you retrieve these 

sequentially, the order of retrieval is inverted. The last record of a string added to overflow, 

chained from a given record, is the first retrieved. 


This “‘last in, first out’’ (LIFO) retrieval sequence results automatically when you chain a 
series of overflow records from one prime record and is satisfactory for some applications. 
However, when you want some other order in sequential retrieval, you may set up the file 
for this when you provide ASAM, for each new record, with the address of the record 
(which may be overflow or prime) from which it is to be chained. 


Note that there is no pushdown or relocating of records added to the overflow area; the 
physical location of a new record blocked into overflow is not determined by the position of 
the prime record from which it is chained nor by the relative location of other records 
chained from the same prime record. 
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é 
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- fourth prime - 


first prime \: 
- | (one addendum) 


~ | (one addendum) | 


third prime: 
(one addendum) 


=. second prime 
(no addenda) 








Prime Data Area 










addendum to 
fourth prime 










addendum to 
third prime 


addendum to 
first prime 





Overflow Area To start of next 
prime record 


LEGEND: 


bh Block header, a 2-byte field written by data management at the head of each physical data block to indicate 
the number of bytes of usable data in the block. 


rp Record pointer, a 5-byte field inserted by data management following each logical record in the data block. 
Those inserted following the prime records initially loaded into the ASAM file were originally dummied and 
contained the hexadecimal pattern FO AA AA AA AA. This pattern indicated that no related record had been 
added in overflow, chained from this prime record, and that the next record in logical sequence was therefore 
the next in physical sequence. When the overflow records were added, data management rewrote the record 
pointers following those prime records from which an overflow record was chained. The pointer following the 
first prime record, for example, points to the start of its addendum record in overflow; the pointer after the 
second prime data record (for which no overflow record was added) still contains the a pattern pointing 
to the next sequential record, in the prime data area. 


Logical data records, prime and overflow, provided by the user. 





Supplied by OS/3 ASAM. 
| 
NN Unused space in physical data block. 


Figure 10—9. Logical Aspect of an ASAM File Containing Not More than One Record Chained in Overflow from Any One 
Pane Data Record 


Oey, 


OO, 


“ea 
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RESULT OF FIRST ADD: 
Prime Data Area 















first 
prime data 
. record 


Overflow Area 







first addendum 
chained from 
first prime 








unrelated to 
first prime 


RESULT OF SECOND ADD: w : , 2 i agg 


Prime Data Area 













first - 
-. Prime data 
, ,fecord 


Overflow Area 



















first addendum 
chained from 
first prime 


} second addendum 
chained from 
first prime 







unrelated to 
first prime 


RESULT OF THIRD ADD: 
Prime Data Area 





first 
prime data 
record 


Overflow Area 








first addendum 
chained from 
first prime 














third addendum 
chained from 
first prime 


second addendum 
chained from 
first prime 







unrelated to 
first prime 


Figure 10—10. Logical Effect of Successively Adding Three Records in Overflow, Chained from Same Prime Data Record of 
an ASAM File 
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10.3.1. ASAM Data Formats 


The formats of the ASAM data records and data blocks are the same as in OS/3 ISAM, 


and separate figures of those for ASAM are not necessary. Figures 10—2, 10—3, and 


10—4 illustrate both keyed and nonkeyed records. Bear in mind, when you review these 
figures for ASAM, that you will be most likely to omit record keys when you want to omit 
the construction and use of an index structure. If you key in your ASAM file, your records 
will look like the keyed examples illustrated. 


10.4. MULTIVOLUME ISAM FILES 


You may split an ISAM file across several disk volumes. It is important to remember that 
all volumes of a multivolume ISAM file must be mounted online for all file processing: 


During your load operations, data management monitors continually to ensure that it does 
not exceed the prime data area you have allocated. If your load fills the prime: area of a 
volume, data management continues the load onto the succeeding volume, if there is one. 
If there is no other volume, it seeks additional space on the current volume and notifies 
you if there is no additional space available. When you terminate the load, data 
management saves the progress point for later use if you should extend the file. 


LOO, 
4 4 
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11. Functions and Operation of ISAM 


11.1. GENERAL 


In the previous section, the discussion of the OS/3 indexed sequential access method 
(ISAM) aimed primarily at describing file organization, data record and data block formats, 
and the format of the index blocks in the index structure that is characteristic of the 
traditional ISAM file. The salient feature of processing an ISAM file that you have 
constructed with a directory or index structure is the search-by-key function, which is 
used to retrieve your records by key. 


We also pointed out the option for creating a nondirectory ASAM file, in which your 
records need not be keyed, and for which data management builds no index structure. 
Accessing records directly without use of an index is accomplished by providing record 
pointers, rather than keys. Sequential processing of either type of ISAM file is essentially 
the same. In our discussion of the structure and content of OS/3 ISAM files, we gave you 
a certain insight into the means OS/3 provides for processing them. 


This section builds on that foundation, presenting first an overview of OS/3 ISAM 
functions. It then presents a declarative macroinstruction, DTFIS, of a specific type, with 
which you define your file to OS/3 data management and outline to OS/3 ISAM some of 
your intentions for processing it. The DTFIS macro establishes a file control table that data 
management uses, during its processing of your file, to keep you and itself informed of the 
characteristics of the file and the results of processing. (Both the macro and the file table 
it creates are frequently termed the ‘‘DTF,”’ from the initials of the phrase define the file 
we use to distinguish this type of declarative macro from others.) 


You describe significant characteristics of your ISAM file, and provide OS/3 data 
management with certain particulars it needs for processing it, by means of some 27 
keyword parameters that you specify as operands of the DTFIS declarative macro. Two of 
these keywords, which provide the size and symbolic name of the input/output area (or 
1/O buffer) that every OS/3 data management file needs for its exclusive use, are always 
required. Most of the other keywords are mandatory under certain conditions or for certain 
processing functions. Others you will specify entirely at your option. The greater part of 
the DTFIS macro discussion concerns its keyword parameters. 
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Following the detailed descriptions of the keywords, this section then presents the set of 
12 imperative macroinstructions that make up the OS/3 data management repertoire for 
processing your ISAM files. Each macro is detailed individually, and the discussion of each 
one points out any way in which your use of it will change when you use it with the 
indexed form or the nondirectory form of OS/3 ISAM. 


Next, we explain the methods you have of linking your program to the OS/3 ISAM 
processing modules. An explanation of OS/3 ISAM’s system for handling error and 
exception conditions follows this, and recapitulates certain points made during 
descriptions of the imperative macros. A number of programming examples conclude the 
section. 


11.2. FUNCTIONAL DESCRIPTION, OS/3 ISAM 


Perhaps the best way to obtain a quick overview of the functions for which OS/3 ISAM 
has been designed is to look at the imperative macros you will issue in your basic 
assembly language (BAL) program to process your ISAM files. But, before studying each of 
these macros in detail (they are described fully in 11.5), it may be more useful to consider 
their functional groupings; these are discussed in the next two paragraphs. 


11.2.1. Processing an Indexed ISAM File 


As you have noted in Section 10, OS/3 ISAM is provided primarily to enable you to 
organize and process disk files from which you will have frequent need to retrieve records 
directly by key, but for which sequential processing is also important to you. ISAM 
facilitates the search-by-key function by providing a key-based index structure; it 
implements this function through a repertoire of key-related imperative macros. OS/3 
ISAM also provides you with a set of imperatives for sequential processing. Table 11—1 
lists the imperatives available for processing an indexed ISAM file. The imperative macro 
calls are grouped in sets according to functions and are repeated to point out that some 
are used in more than one setting. Note that those you would expect to call many times in 
your BAL program have been indented in the list to identify them. (The name of the ISAM 


—> file in the illustration is “EMPLMST” - possibly a master file of employees at some 


installation.) 
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‘Table 11—1. Imperative Macro Calls for Processing an OS/3 ISAM File with an Index Structure, Listed by Functions 


Initiating and Terminating OPEN EMPLMST 
Processing of the File CLOSE EMPLMST 


Loading or Extending SETFL EMPLMST 
the File . WRITE EMPLMST, NEWKEY 
ENDFL EMPLMST 


Inserting New WRITE EMPLMST, NEWKEY 
-Records bed WAITF EMPLMST 


Random Processing. . -_ READ EMPLMST, KEY 


Retrieval and Updating WAITF EMPLMST 
if WRITE is used READ EMPLMST, ID 
WAITF EMPLMST 
WRITE EMPLMST, KEY 
WAITF EMPLMST 
BOF 
- Sequential Processing. EMPLMST, KEY 
Retrieval and Updating GKEY 
if PUT is used ID | 
aa ee - GET EMPLMST, (0) 
PUT EMPLMST 
ESETL EMPLMST 





NOTES: 


1. The ADD imperative macro is equivalent to the WRITE,NEWKEY 
macro for inserting new records, 


2. The UPDT imperative macro is equivalent to the WRITE,KEY macro 
for random updating. 


11.2.2. Processing an ISAM File without an Index Structure 


When you specify a nondirectory ISAM file, you can no longer locate records by presenting 
a key to data management. Three of the standard imperative macros are no longer 
available to you: 


READ, KEY 
SETL, KEY 
SETL, GKEY 


Otherwise, the function repertoire is the same. Bespits the fact that Keys are not used, 
some macro calls retain the KEY eperanes: 


The WRITE, KEY macro, for example remains available to you for inserting a trailer record 
in overflow, but you provide this macro with the plane address of the header record from 
which the taller depends) not its key. 


Sequential ppoeeseias is the same as for indexed files, except that no index is available for 
selecting the starting point for a sequential retrieval sequence. Here again,. you will 
provide a relative record address to the SETL macro. 
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Table 11—2 lists the calls for the imperatives available for processing a nondirectory ISAM q 
file. The calls are grouped in sets according to functions and, as in Table 11—1, are a 
repeated to indicate that some operate in more than one setting. Those calls that you 

should expect to use many times in your BAL program are indented to identify them. 

(Again, the 7-character file name of the nondirectory ISAM file’ being processed in the 
illustration is ‘““EMPLMST.”’) 


Table 11—2. Imperative Macro Calls for Proreeeing a Nondirectory 0s/3 ISAM File without an Index Structure, Listed by 
Functions 


Functions imperative Macro Calls — 


Initiating and Terminating OPEN EMPLMST 
Processing of the File ~ CLOSE EMPLMST 


Loading or Extending — SETFL EMPLMST 
the File ml . WRITE EMPLMST, NEWKEY 
ER ae ENDFL EMPLMST 


Adding Trailer WRITE EMPLMST,NEWKEY 
Records WAITF EMPLMST 


Random Processing. READ EMPLMST, ID 
Retrieval and Updating WAITF EMPLMST 
if WRITE is used WRITE EMPLMST, KEY 
WAITF EMPLMST 
ake 
Sequential Processing. SETL EMPLMST, er ( F 
Retrieval and Updating “ 
if Put is used GET EMPLMST, (0) 
PUT EMPLMST 
ESETL EMPLMST 





NOTES: 


1. The ADD imperative macro is equivalent to the WRITE,NEWKEY 
macro for inserting new records. 


2. The UPDT imperative macro is equivalent to the WRITE,KEY macro 
for random updating. 


11.2.3. Deleting Records from an ISAM File 


A function for which OS/3 ISAM does not provide you a specific imperative 
macroinstruction is record deletion. However, to help you in this aspect of managing a file, 
OS/3 ISAM establishes a 2-byte field in the DTFIS file table (half-word-aligned) in which 
your ‘program may keep:a count of the number of records you have tagged for deletion. 
You may address this field, which is available for the life of the file, by concatenating the 
character “‘T”’ to your 7- character file name; this field will Poe terines mae in this 
manuals 


You, of course, must establighe your own convention for saodiiiG ‘caeords in your file that 

are to be deleted; there is no field in the OS/3 ISAM data formats dedicated to this use oo 
(nor, if you recall; does OS/3 ISAM provide for user file labels in which you might record 
. deletion statistics instead of using ACH aIET) : 
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Because tagging a record for deletion will most likely be part of a rewrite operation (for 
which you issue the WRITE, KEY macro), it would be logical also to increment the count in 
filenameT either before or after the rewrite operation. Because your count of records you 
have tagged for deletion is always available to you in the DTF, you can access it.as an aid 
in deciding when to reorganize your ISAM file. 


There is no way to avoid retrieving records you have tagged for deletion; they will always 
be read by a READ or GET imperative macro. For this reason, to tag records that you have 
decided should be removed from the file is an important part of your processing them. You 
should, of course, also. provide in your program for ene against the presence ‘of this 
flag whenever you retrieve a record. 
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DTFIS — 


11.3. DEFINING AN 0S/3 ISAM FILE (DTFIS) 


In order to process a file by OS/3 ISAM, you must define it to data management by 
issuing the DTFIS declarative macro in your BAL program. (The macro call is 5 derived from 
the pases define the file for indexed sequential.) 


The symbolic name , of your file (filename) may contain no more than seven characters and 
must begin with an alphabetic character. This file name is also used by the OS/3 ISAM 
imperative macros to identify the file to be processed. It must be the same as the file 
name you have included in the LFD statement in the device assignment set of OS/3 job 
control statements by which you allocate the file. (See the job control user guide, UP-8065 
(current version) for the details of OS/3 job control statements.) 


The DTFIS declarative macro generates a file table that data management uses to keep 
itself and you informed of the characteristics of the file and of the results of your 
processing it with the ISAM imperative macros. The DTF generator assures that the file 
table is automatically aligned on a full-word boundary. The size of this file table varies 
according to the processing to be performed (which you may specify via the |OROUT 
keyword parameter, 11.4.8): 


DTF File Table Size, 


in Bytes IOROUT Specification 
332 LOAD 

372 RETRVE 

396 ADD 

396 ADDRTR 


As you execute each imperative macro, data management places an informative reply, 
indicating normal completion or exceptions (including unrecoverable error conditions) in a 
special field of the DTF file table. If you have not provided an error exit, you must 
remember to access this field when control returns inline to you after execution of each 
imperative. 


You address this field (called filenameC) by concatenating the character “‘C’’ to the name 
of your file. Some of the imperative macros also pass information to you in other special 
fields of the DTF file table, which you may address similarly by concatenating a specific 
character to your file name (details are given for each macro separately in 11.5, and these 
are recapitulated in 11.7). Because the maximum length for symbolic names throughout 
OS/3 is eight characters, data management therefore limits you to a maximum of seven 
for file names. 


In addition to the file table just mentioned, the DTFIS declarative macro also generates 
certain references so that you may link a BAL program with a DTFIS file table you have 
generated in a separate assembly: 


# An ENTRY definition for filename. You must specify a corresponding EXTRN definition 
for filename within your program. 
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# An EXTRN definition for each symbolic name you have supplied with certain of the 
DTFIS keyword parameters described in what follows. You must specify a 
corresponding ENTRY definition for each of these symbolic names. 


Following is a listing of the required and optional keyword parameters you will specify as 
operands of the DTFIS declarative macroinstruction. These are listed here in alphabetic 
order, but you may specify them in any convenient order, just So you separate them with 
commas. The paragraphs following this format statement discuss the use of each keyword 
parameter, and a table summarizing the keywords follows the descriptions. 


Refer to the preface of this manual for OS/3 data management format statement 
conventions and to 1.6.3 for rules concerning continuation of statements. A comma is 
shown preceding each keyword parameter except the first, to remind you that all keywords 
coded in a string must be separated by commas. However, a comma must neither be 
coded in column 16 of a continuation line, nor follow the last keyword in the string. Refer 
to the coding examples which follow. 


Format: 







A OPERATION A OPERAND 








filename ACCESS= ( EXC 
EXCR 
SRD 
\SRDO 
BLKSIZE=n 


[,ERROR=symbol] 
[,INDAREA=symbol] 
[INDEXED=NO] 

| INDSIZE=n] 
,OAREA1=symbol 

[ LOAREA2=symbol] 
[ JOREG=(r)] 


IOROUT=( LOAD 
ADD 
RETRVE 
ADDRTR 


[,KEYARG=symbol] 
[ KEYLEN=n] 

[ KEYLOC=n] 
[,LOCK=NO] 


[, PCYLOFL=nn] 
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LABEL A OPERATION A OPERAND 
filename ,RECFORM= SORES \ 
(cont) VARBLK 


[ ,RECSIZE=n] 
[ SAVAREA=symbol] 


"TYPEFLE= ( RANDOM ) 
RANSEQ 
SEONTL 

LUPDATE=NO] 

[, VERIFY=YES] 

[WORK 1=symbol] 


[,WORKS=NO] 





11.4. DTFIS KEYWORD PARAMETERS 


The following is a discussion of the use of each of the keywords that you may specify as 
operands of the DTFIS declarative macroinstruction; the discussions are arranged 
alphabetically for ease of reference. Table 11-3, following these Ses HIPUODS: summarizes 
all of the keywords. 


11.4.1. Specifying File Accessing Options (ACCESS) 


In a multitasking environment, the file lock feature can prevent the loss or destruction of 
data. This feature allows you to control the sharability (specify the read/write 
requirements) of a file while you are using it. This feature only applies to those files you 
specified as lockable. The procedure for specifying which files are lockable is described in 
16.1.4. 


You can specify the sharability of a lockable file by using either the ACCESS or LOCK 
keyword parameter (11.4.1). It is recommended that you use the ACCESS parameter 
because it provides greater flexibility (more read/write options available) than the LOCK 
parameter. If both the ACCESS and LOCK parameter are specified in the same DTF 
macroinstruction, the ACCESS specification will override the LOCK specification. 


Keyword Parameter ACCESS: 
ACCESS=EXC 
Specifies exclusive read/update/add use of the file. No other jobs can access the 
file while it is being used. 


NOTE: 


This specification is equivalent to the default value for the LOCK parameter, that ts, 
LOCK=NO is omitted. 


a ag 
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ACCESS=EXCR 
Specifies read/update/add use of the file and also allows other jobs to read from 
the file while it is being used. (Only ACCESS=SRD can be epee for other 
jobs.) 


ACCESS=SRD 
Specifies that. only the read function is allowed for the file and allows other jobs 
read/update/add use of the file. (Only ACCESS=EXCR, SRD, or SRDO can be 
specified for other jobs.) 


ACCESS=SRDO , . 
Specifies that only the read function is allowed for the file and also allows other 
jobs to read from the file. Writing to the file is not allowed from the job 
associated with this DTF or from other jobs. (Only ACCESS=SRD or SRDO can 
be specified for other jobs.) 


11.4.2. Specifying Size of Data Blocks (BLKSIZE) 


To ‘specify the size of the physical data blocks in your ISAM file, you must supply this 
required keyword parameter in your DTFIS declarative macro. (See 10.2.2 for a discussion 
of ISAM data block formats; these are shown in Figure 10—4.) 


Keyword Parameter BLKSIZE: 


‘BLKSIZE=n 
Specifies the size of the blocks in the file, where n is the size in bytes. This 
keyword is always required. Size may not be less than 256 bytes nor exceed 
the track size for the disk subsystem on which the file resides: 


SPERRY UNIVAC Track Size, 
Disk Subsystem in Bytes 


8411 3625 
8414 ~ 7294 
8415 10,240 
8416 10,240 
8418 10,240 
8424 7294 
8425 7294 
8430 13,030 
8433 13,030 


When you specify fixed-length records (by default, or by _ specifying 
RECFORM=FIXBLK), your BLKSIZE specification nm should equal record size + 5 bytes, 
multiplied by the number of records per data block, adding two bytes for the block 
header. The block size need not be the same as your I/O buffer allocation, which may 
be specified with a define storage (DS) statement elsewhere in your program, but it 
must not exceed the length of the buffer. 
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When 8415 disks are used, the ISAM blocksize is restricted. For each cylinder, ISAM 
requires at least two blocks of space reserved for overflow. The following algorithm 
calculates b, the total number of overflow blocks per cylinder: 


b = blocks per track x tracks per cylinder 


A minimum of one block per track may be specified and two tracks per cylinder (8415 
removable) or three tracks per cylinder (8415 fixed). The number of blocks per cylinder is 
then multiplied by the percentage of overflow (maximum 80%) and rounded up to the next 
integer value. If less than two, the resulting overflow block count is set to 2. The overflow 
block count is then subtracted from the total number of blocks per cylinder. to calculate d, 
the data blocks per cylinder, a a Nanne which must be nonzero. 


d = b — overflow block count 


When applied to the 8415 disk (fixed or removable) the algorithm for calculating number of 
overflow blocks per cylinder (b) can result in a value identical to the total number of blocks 
per cylinder, thus leaving no space for data. If this condition occurs, the OPEN imperative 
macro generates the message: DM61 INVALID DTF FIELD: PARAMETER, OR PARAMETER 
COMBINATION. This restriction condition can occur only with large block sizes (one or two 
blocks per track) and large overflow percentages (70 to 80%). 


11.4.3. Specifying Your Error Exit (ERROR) 


When a fatal hardware or detectable logic error occurs on an ISAM file, or an exception is 
detected to exact performance of the function you have requested, data management 
returns control to your error-handling routine, if you have coded one and provided its 
address with the ERROR keyword parameter..lf you have no error routine, control returns 
to you inline, at the instruction in your program next after the imperative macroinstruction 
that initiated the transfer of control. 


It is your responsibility to interrogate the error/status codes and take appropriate action. If 
you choose to continue processing, it is useful to know that data management provides 
you an inline return address in register 14; this inline return is to the instruction in your 
program next following the imperative macro that. mitehed the transfer of control to your 
error routine. 


When OS/3 data management transfers control, the addressable field filenameC in the 
DTFIS file table contains information on the reasons for the error. (See 11.7 and Appendix 
B.) - 


meyer’ Parameter ERROR: 


ERROR=symbol ae 
Specifies the address of your error- fandiaa’ routine, to aanich data ianaseneet 
transfers control for all conditions of error or exception to exact performance of 
the function you have requested. When data management transfers control, 
filenameC contains information on the reasons for the error. 


If omitted, control returns to you inline. 
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11.4.4. Describing an Index Area in Main Storage (INDAREA, INDSIZE) | 


This pair of keyword parameters is required when you are /oading an indexed file but 
_ optional at other times. (It is not used when your file is.a nondirectory ASAM file and has 
no index.) You specify a main storage location into which ISAM may load part of your top 
-index by the INDAREA keyword, and you specify the length of this area, in bytes, with the 
| INDSIZE keyword. Like the I/O area, your index area must always be half-word aligned. 


For loading operations, the length a ‘the index area must always be at least 256 bytes 
because ISAM uses this space to create the 256-byte index blocks as loading ploceece 
(See 10.2.3.) : | 


_ An optional OS/3 ISAM facility, by which ISAM places all or part of the top index in main 
storage to speed random retrieval or record insertion, may be invoked by specifying the 
INDAREA and the INDSIZE keywords under the following conditions: 


# The KEYARG and KEYLEN keywords are also specified (11.4.9, 11.4. a 
-@ — 1OROUT=ADD, ORO vse Rnie or IOROUT=RETRVE is also specified a1 4. 8). 
Z TYPEFLE= RANDOM. or TYPEFLE= RANSEQ is. ‘also specified (11 4, 18). 


The INDSIZE, INDAREA, and KEYLEN parameters define the size and ne of the index 
buffer and the amount of the top index that.:may be brought into main storage 
automatically when the file is opened. ISAM determines the size of the top index table 
entries from the length of keys specified by the KEYLEN keyword and ensures that the 
length of the INDAREA table (specified: by the INDSIZE keyword) will accommodate at least 
one block of top index entries. If your INDSIZE specification is less than this minimum, 
your attempt to invoke this facility” ‘is negated, and appropriate diagnostic messages are 
printed in the DTFIS macro expansion-in your assembly listing. ISAM automatically rounds 
eur INDSIZE ehecitication down to an: uateger mennPre of one: ‘block of tO: index entries. 


To ascertain the total number of ‘bytes aétualty reguiied to hold the entire this: entire top 
index in table form in the INDAREA buffer, you may access filenameS in. the DTF on 
completion of a file load sequence; refer to 10.2.4. 


For a description of the operation of the ISAM index-in-main- ‘storage facility oe to 
10.2.5. 


‘Keyword Parameter INDAREA: 


INDAREA=symbol 
Specifies location in main storage in which ISAM builds index. blocks during load 
operations, or where ISAM places top index table for random retrieval or record 
insertion, where symbol (address) is the location. Must be half-word aligned. 
Required for load operations; opnene! ad eels: Length area Spepiice by 
INDSIZE Keywere 
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Keyword Parameter INDSIZE: 


INDSIZE= =n . 
Specifies length of index area in main storage, where 7 is the length, in bytes. 
_ For load operations, the length must be at least 256 bytes; excess space is 
_ unused. For random processing, length greater than 256 bytes is optional; ISAM 
‘ensures that INDAREA accommodates at least one block’ of top index entries 
(three bytes greater than KEYLEN specification). 


11.4.5. Eliminating the Index Structure (INDEXED) 


This keyword is used when you want to eliminate construction of the ISAM index 
structure. | ! : : : 


Keyword Parameter INDEXED: 


INDEXED=NO 
Specifies that you have elected the option to create a nondirectory ISAM file and 
to reference its records by relative addresses, rather than by keys. Data 
management does not construct the index; key-based processing functions are 
noperaiNe: 


If omitted, the index structure i is s provide, 


41 4.6. Specifying 1/0 Buffers (OAREAI, lOAREA2) | 


All ISAM aperstions require at least one 1/0 area, half- word: aignad ne at least 256 
‘bytes in length. You specify its address with the IOAREA1 keyword. You may specify a 
second area, of equal size, which must also be aligned on a half-word boundary, with the 
optional IOAREA2 keyword. To do so will increase the speed of your processing; you will 
notice that the benefits are more pronounced for Joad: and sequential retrieval than for 
-random operations.. 


Reymond Parameter IOAREA1: 


1OAR EA1 =sym Bel. 
Required to specify location of input/output area, where symbol (address) is he 
location. Must be half-word aligned. Length must. equal or exceed the number of 
bytes specified with BLKSIZE keyword. 


Keyword Parameter IOAREA2: 


l|OAREA2=symbol . 
Specifies location of optional - additional input/output area, where symbol 
(address) is the location. Must also be half-word aligned and will be same size as 
the required area specified by the IOAREA1 keyword. You may improve the speed 
of sequential |/O operations if you specify this keyword. 


j 


UP-8068 Rev. 4 SPERRY UNIVAC OS/3 _ -. 11-13 


BASIC DATA MANAGEMENT... 





11.4.7. Specifying Current Record Pointer (IOREG) 


When you are referencing your records in the I/O areas rather than in the work. areas, 
you need to specify a general register to be used to point to the current I/O area. 
Registers 2 through 12 are always available; if you have specified the SAVAREA keyword 
parameter, general register 13 is also available. (See 11.4.18 for details on the use of 
record work areas.) 


Keyword Parameter IOREG: » 


‘ lOREG= (r) . 
Required to specify ‘the sénéral register to ‘be uae: to point to fhe? current I/O 
area when you are not referencing records in the work areas, where r is the 
number of the general register. Registers 2 through 12 are available, and register 
- 13 is also available if you have specified the SAVAREA keyword. 


11.4.8. Specifying the Type of File Processing (IOROUT) 


You may specify the type of processing tobe performed on your ‘file with the optional 
IOROUT keyword; this parameter has four forms. Note that you may also. specify the type 
of retrieval with the TYPEFLE keyword (11.4.15). 


A file-loading operation (IOROUT=LOAD) may end with the final data block only partly full. 
When this occurs, data management stores the exact location of unused file space in the 
disk volume table of contents (VTOC) for later LGSOvEnY and use as needed. 


You may add sacerds (oROUT=ADD) with keys higher ‘than the final prime . data Facord, 
which is contained in the data block marked .as the logical end. of file. As. data 
management places: these in overflow, they do not: eanert the location. of unused prime . 
space. | are . . 


If you should introduce new records . resuming load operations (IOROUT=LOAD), these 
must be submitted in ascending order of keys; all must have higher keys than the current 
nignest key eel ina Ppume record or an overflow record already on disk). | 


If you add enough records to an ISAM file, some Sy aden oveflow. space will Became filled, 

and data management will be unable to place added records on the cylinder where they 
belong. When this occurs, data management resorts to using space on the earliest cylinder 
having available overflow and adds records at the earliest possible point of the following 
sequence: 


1. On the cylinder reached by prime search 
2. On the cylinder having the current COCRS* | 


3. Ona cylinder newly set as having the COCRS (discovered by progressing through 
COCR blocks to one showing space available) 


*The COCRS is a special cylinder overflow control record that data management writes and maintains in the DTF and 
V7OC to control remaining overflow space on the cylinder that is currently used to accept overflow records from other 
cylinders. 
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Keyword Parameter IOROUT: 


IOROUT=ADD) a 2H 


Specifies that new records are to be inserted into a file. You may not specify the’ 


ADD form of this keyword unless you have allocated an oyerve™ area with the 
PCYLOFL keyword parameter (11.4.12). | 


IOROUT=ADDRTR 
Specifies that new records are to be inserted in the file and that records will also 
be retrieved and updated randomly or sequentially. You may not specify the 
ADDRTR form of this keyword unless you have allocated an overiony area with 
‘the PCYLOFL keyword (11.4. es , 





Specifies t at either a new file is to be created or an existing file is to be 
extended. ISAM assumes that the LOAD form has been specified if you omit the 
IOROUT keyword parameter. 


_ lOROUT=RETRVE 
Specifies that your records are to be- retrieved or updated rancomy or 
sequentially. 


_If omitted, IOROUT=LOAD is assumed. Type os ceievel may be ‘specified with the 


TYPEFLE keyword (11.4. 15). | 


11.4.9. Specifying Location of Retrieval Search Argument (KEYARG) 


Whether you are eetecancing scons by key (as when you are using ISAM with the index 
structure) or by relative address (as with the nondirectory form of ISAM), you need: a field 
in which to present data management either with the key it is to match by the search-on- 
key function or with the relative disk address at which it is to access your record GUGEUY: 
You specify this field with the ren neywerd parameter. 


You should. avoid presenting ISAM with either: the address or the all-zero key of the 
dummy record at file start as a search argument. The dummy record is not available for 
you to use, and efforts to retrieve or overwrite it result in the error processing described 


under the various imperative macros involved. You may, on the other hand, safely specify 
an all-zero key in the KEYARG field when you issue the SETL, GKEY imperative: data 
management prepares to give you the first record after the dummy, and no error 


processing results. 


The length of the KEYARG area will be five bytes when you use it only for relative 
addressing, but it must equal the actual length of the keys in your records (specified by the 
KEYLEN keyword) when you are using the indexed form of ISAM. You may omit the 
KEYARG keyword parameter when you are not retrieving records. 
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Keyword Parameter KEYARG: 


KEYARG=symbol | 
Specifies the field in your program where you will place addresses or keys to 
effect retrieval of your records, where symbol (address) is the location in this 
field. The length of the KEYARG area is five bytes when you use it for relative 
addressing and equal to key length (KEYLEN keyword parameter) otherwise. May 
be omitted when you will not retrieve records. 


11.4.10. Specifying Length and Location of Records Keys (KEYLEN, KEYLOC) 


When your records have keys (as they must when you use the indexed form of ISAM, and 
may when you are using the nondirectory form), all keys in the file must have the same 
length, and every record must have a key. The key need not begin at the head of the 
record; it may be internal to the record, in fact, but the starting place for the key must be 
the same in every record. The minimum length for a key is 3 bytes; the maximum is 253. 
Each key must be unique. No byte of any record’s key may contain the hexadecimal value 
FF, nor may any of your keys duplicate the all-zero key or the dummy record that ISAM 
creates and inserts at the start of the file. 


You specify the length of the key in bytes with the KEYLEN keyword parameter and the 
number of bytes of data that precede the key with the KEYLOC keyword. You must specify 
the KEYLEN parameter for an indexed ISAM file; you need not specify it for a nondirectorty 
file unless you want ISAM to check the sequence of your keys during the load operation 
(remember that sequence checking is done automatically only when you are loading your 
records for an indexed ISAM file, to which you present them in ascending order of keys). 


You need not specify the KEYLOC keyword if the key is at the head of the record. When 
you omit this keyword, ISAM assumes that you have specified KEYLOC=0 for fixed records 
or KEYLOC=2 for variable records (each of which, as you recall, contains its record length 
in the leading two bytes). 


Keyword Parameter KEYLEN: 


KEYLEN=n . 
Specifies the length of keys in an ISAM file, where rn is the length in bytes. All 
keys in an ISAM file must have the same length; the minimum length is 3 bytes, 
and the maximum is 253. Required for indexed ISAM files; optional otherwise. If 
specified for a nondirectory ISAM file, causes data management to check 
sequence of keys during a record load. 


Keyword Parameter KEYLOC: 


KEYLOC=n 
Specifies the number of bytes that precede the key of an ISAM record, where n 
is this number. The location of the keyfield must be the same within all records 
of the file. 


If omitted, ISAM assumes that you have specified a value of zero for fixed records or 
two for variable records. 
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11.4.11. Suppressing a File Lock (LOCK) 


As we mentioned earlier, there are two ways to specify the sharability of your disk files. We 
have already discussed the ACCESS keyword parameter and now we will discuss the other 
way: that is, the LOCK keyword parameter. 


Two options are available with the LOCK parameter: 


1. The file is exclusively locked when it is opened during the execution of your program. 
You have exclusive use of the file. You can read, update, and. add | to the file. No other 
user can open the file until you close it. 


2. A read-only lock is applied to the file when it is opened. You can only read from the 
file and all other uses can only read from the file. 


Keyword Parameter LOCK: 


LOCK=NO 
This is equivalent to specifying ACCESS=SRDO. It should not be used in the 
same DTF as the ACCESS keyword parameter. If it is, the ACCESS keyword 
parameter will override it. 


If you omit both LOCK=NO and the ACCESS keyword parameter, this is equivalent to 
specifying ACCESS=EXC. 
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11.4.12. Providing Cylinder Overflow Area (PCYLOFL) — 


For both the indexed and the nondirectory ISAM file, you specify the percentage of the 
space of each cylinder that data management is to reserve for overflow with the PCYLOFL 
keyword parameter. You will recall that it is to the overflow area that data Manageniont 
writes records added after your initial en The maximum percentage is 80. 


If you specify a zero value or if you omit the PCYLOFL keyword altogether, you may not 
add records to the file; any you attempt to insert will be rejected. 


Keyword Parameter PCYLOFL: 


PCYLOFL=nn 

_- Specifies the percentage of each andar that data management is to reserve for 
overflow, where nn is the percent. The value of mn may range from OO through 
80. If you specify PCYLOFL=OO, records presented later for insertion will be 
eplected! 


If sniea: data management assumes that you have specified PCYLOFL=OO. 


11.4.13. Specifying Record Size and Format (RECFORM, RECSIZE) 


Records in an ISAM file are fixed or variable in length and are blocked by data 
management. You may specify the format with the RECFORM keyword parameter; if your 
records are fixed length, you must specify this length with the RECSIZE keyword. All fixed 
records must have the same length in an ISAM file. 


Keyword Parameter RECFORM: 


RECFORM= FIXBLK : 
Specifies that your records are fixed-length, blocked. You must also specify the 
RECSIZE keyword. 


RECFORM=VARBLK 
Specifies that your records are variables length, blocked. You do not specify the 
RECSIZE keyword. 


If omitted, data management assumes that you have specified RECFORM=FIXBLK, 
and you must Specity the RECSIZE keyword parameter. © 


Keyword Parameter RECSIZE: 


RECSIZE=n 
Specifies the length of fixed records, where rn is this length, measured in bytes. 
Required for fixed-length records only; must be specified if you omit the 
RECFORM keyword. Not used for variable records. 
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11.4.14. Specifying a Save Area for Contents of General Registers (SAVAREA) — 


Before you issue an imperative macro for processing any OS/3 data management file, you 
may first load general register 13 with the address of a 72-byte labelled save area — 
always. aligned on a full-word boundary — in which data management will expect to save 
the contents of your registers. If you do not want to provide this. information with every 
call, you may place the location of the save area in the DTF file table by specifying the 
SAVAREA. keyword. Refer to 1.4 for the content of this area. 


Keyword Parameter SAVAREA: 


SAVAREA=symbol 
Specifies the address of a 72-byte labeled save area for the contents of general 
registers, full-word-aligned, where symbol (label) is the address. Used only when 
register 13 is not loaded with save area address before each issue of imperative 
macros to the file. 


If omitted, data management assumes that you have preloaded register 13 with 
address of a save area before issuing each imperative. 

11.4.15. Specifying the Type of Retrieval (TYPEFLE) 

When you are performing retrieval operations on your ISAM file, indexed or nondirectory 

(and therefore have. specified |IOROUT=RETRVE or. IOROUT=ADDRTR (11.4.8.)), you may cc 

specify the type of. processing (random or sequential) with the TYPEFLE keyword Se 

parameter. You do not use the TYPEFLE keyword unless you are retrieving records. | 


Keyword Parameter TYPEFLE: 


TYPEFLE=RANDOM 
Specifies that random (direct) retrieval operations are to bis performed. 





Snetifies ‘that ‘sequential retrieval operations will be performed. 


TYPEFLE= RANSEO 
Specifies that both random and sequential retrieval will be peformed. 


| if omitted, data management assumes that you have specified TYPEFLE= SEONTL. Not 
used unless records are to be retrieved. |OROUT=RETRVE or IOROUT=ADDRTR must 
also be specified (11.4.8). 
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11 o 16. aye nee of Update Functions rete 


When you want to aveid the possibility of indecently writing to an ISAM file that’ you 
intend to be a read-only file, you may specify the UPDATE keyword parameter in the DTFIS 
macro. This keyword sets a bit in the DTF file table that causes data management to set 
the invalid macro error flag (byte O, bit 6) in filenameC if you should'issue a PUT or WRITE 
imperative macro to this file, and you then may take no action on the file omer than to 
close it. ieee Gauls, B.) ee 


Keyword Pa ra meter UPDATE: 


UPDATE=NO 
' Specifies -that data wianadenient | is to flag a subsequent issue of the PUT or 
WRITE: macro as an invalid macro (byte O, bit 6 of filenameC); no further 
reference to the file, other than to close it, is posslples. 


If omitted, the possibility of inadvertent updating of the file is not forestalled. 


11.4: 17. "Specifying Parity Check of f Output Records (VERIFY) 


When. you need data management to. “make a parity check of your records: after it has 
written each one to disk you must specify the VERIFY keyword parameter; otherwise, no 
check reading will be done. You should remember that specifying a parity check will 
necessarily increase the execution time required for the PUT and WRITE macros by about 
one rotation period per block. You must weigh this overhead against the aavantage of 
ome slate pomilestien of problems within your file. 


Kener Parameter VERIFY: 


VERIFY=YES ae ee rf 
- Specifies that: data wancasment is to check parity of pirat records after they 
have been written to disk. Necessarily increases execution time for PUT and 
WRITE macros. If bad parity is detected, data management sets output parity 
check flag (byte 2, bit 2) in filenameC and transfers control to POEs error ‘routine 
or to you inline. 


~ If omitted, no output parity verification will be done. 


11.4.18. Specifying Location of Record Work Areas (WORK1, WORKS) 


For loading and adding functions (that is, when you have specified IOROUT=LOAD, 
IOROUT=ADD, or IOROUT=ADDRTR, 11.4.8), you must. provide ISAM with the location of 
a record work area by specifying the WORK1 keyword parameter. Furthermore, unless you 
have selected a general register to be the current record pointer (IOREG keyword be .4.7), 
you must also specify a record work area for random retrieval. 
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For sequential retrieval, you do not specify the location of a record work area-in the DTF, 
and data management ignores the WORK1 ney wong if it is present You nau two other 
epuens for ee retrieval: | ; 


1, Working in ‘the empl buffer. To. do this, you specify ite IOAREAI and IOAREA2 
~<-‘keywords and both the IOREG and the WORKS Key wierd parameiols 


2. cianetening recoils to is work area. ato do this, you ae not: Snotity either the IOREG 
or the WORKS keyword parameter; you specify the location of the work area in the 
second positional parameter of each GET imperative macro you issue (11.5.5.2). 


An important point to remember is that the record work area, however you specify it, holds 
one record at a time. An obvious point is that its size is governed by your record length; if 
your records ‘are variable, the size must accommodate the largest of these.. © 


Keyword Parameter WORK1: 


WORK1=symbol 
Provides the location of a record work area, where symbol (address) is the 
location. Required’ for load and add (functions (when IOROUT=LOAD, 
IOROUT=ADD, or IOROUT=ADDRTR has been specified). Also required for 
random retrieval unless you have epeciied the lIOREG Keyword parameter. Is 
ignored for sequential retrieval. : 


Keyword Parameter WORKS: 


WORKS=NO : 
When IOREG keyword is also specified for Seauieniial retrieval, indicates that you 
will process records in the current input buffer. ; 


If omitted, and IOREG keyword is not specified, data management expects to transfer 
‘sequentially retrieved records (one at a time) to the work area you en as an 
epetane of each GET macro you issue (11. 5.5.2). 


11.4.19. Nonstandard Forms of the Keyword Parameters 


When the assembler is preparing your DTF, it uses a specific list of keywords. Discovery of 
a keyword that is not on the list results in an assembly error. In order that existing 
programs may require minimal changes for assembly in OS/3, the list of acceptable 
keywords has been expanded beyond those listed as standard. The acceptable variations 
are: 


08/3 Standard Acceptable 

BLKSIZE. i an BKSZ | 

ERROR ERRO 

INDAREA . INDA 

INDSIZE INDS 

IOAREA1 IOA1, IOAREAL, IOAREAR, IOAREAS 
IOAREA2 IOA2 


IOREG IORG 
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OS/3 Standard = Acceptable 

lOROUT IORT 

KEYARG KARG 

KEYLEN KLEN 

KEYLOC KLOC 

PCYLOFL PCYL, CYLOFL, CYL 
RECFORM | RCFM 

RECSIZE RCSZ 

SAVAREA SAVE 

TYPEFLE TYPF 

UPDATE UPDT 

VERIFY VRFY | | 
WORK1 WRK1, WORKL, WORKR 


11-21 


Note that there are no acceptable variations for the INDEXED or the WORKS keywords and 
that none of the completion values (the values to which you equate these keywords) may 
vary from. the OS/3 standards given in the preceding paragraphs. 


11.4. 20. Recapitulation of DTFIs Keyword Parameters 


Table 11—3. lists all of the keyword parameters that may be suet as opstands of the 
DTFIS declarative macroinstruction. An example of coding the DTFIS declarative macro 
follows the table. 


Table 71—3. Keyword Parameters of the DTFIS Declarative Macro Instruction (Part 1 of oh 


, : Remarks 
: 


ACCESS* "| This DTF: read/update/add use 
Other jobs: ‘no access 


EXCR This DTF: rada/apHatelada use 
Other jobs: read use 
This DTF: wea use 
Other jobs: read/update/add use 


This DTF: read use 
Other jobs: read use 


BLKSIZE * 


ERROR symbolic labe! roa Address of subroutine to handle errors and exceptions 


INDAREA symbolic label eres EZ Address of main storage area to contain index 
INDEXED. fvo = fF of of of | Specifies that file is not to be indexed 


ee : ve 

INDSIZE n (in bytes) Size of index area in main storage; minimum size 
is 256 bytes. ; : 
IOAREA1 symbolic label pafrial a 





Address of |/O area in main storage 
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Table 11—3. Keyword Parameters of the DTFIS Declarative Macro Instruction (Part 2. of 2). 


pecan 


IOAREA2 symbolic label 


IOREG (r)=general register 


ADDRTR 


RETRVE 


KEYLEN **| on. 


File Function 
Remarks 











Address of a second 1/O area in main storage to speed... 
processing 


i tas , 
Contains address of.the |/O area in main storage. Ga & 


Insert new records to file. ; : 


Insert new records and retrieve records randomly 
or sequentially. 








¥ 








Create new file.or extend existing file. 





Retrieve and/or update randomly or sequentially. 





Address of field containing key of desired record. 






_Key length in bytes for ISAM file. When specified ~. ; 
for nonindexed files, a sequence check of keys is made. ‘| 


Location, in bytes, of the key within a record. If 
omitted, KEYLOC=0 for fixed-length records; 
KEYLOC=2 for variable-length records. 





ae 
Loe 







0 Requests file lock not be set on a lockable file at OPEN 


LOCK 


PCYLOFL 





Percentage of cylinder (blocks) available for overflow 





te 












RECFORM * j1.S8 Specifies fixed-blocked records 


VARBLK S 


SAVAREA |: symbolic label . 0: 
TYPEFLE RANDOM i) 
RANSEO od 


wore [ve 


Specifies variable-blocked records 





Size, in bytes, of fixed records to be processed See! 


\ Address of general register save area 


“Specifies random file processing function ~ . ~ 


Specifies random/sequential file processing function 








Specifies sequential file processing function 





Eliminates update capability 


Specifies a parity check of data records is to be 
made after being written to output disc 





Address of work area for records being loaded, 
reloaded, extended, or inserted - - 


WORK1 symbolic label 





Pep ial 


WORKS NO No record work area available for sequential 
retrieval , 23 

LEGEND: 

L File creation or extension 

A Record insertion 

S Sequential retrieval 

T Random retrieval 

0 Optional 

R— Required 

S Select one 


Value assumed if keyword is not specified. 


*Parameter may be changed by DD job control statement. 
**Parameter may be changed by DD job control statement, indexed mode only. 
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Neal Example: 
LABEL AOPERATIONA OPERAND A COMMENTS 
10 16 72 
LINE, AN! INDEXED, SEQUENTILAL, FILLE. NAMED GRAND... iii baa ci li aial rol 
4 dda Pad gol Ph er dae GLa pack Ge Pao ala aac, ea taeda ak PS oad cil 
RAND .. | DTLALS! (LOROUT=A: DDIRT.R. 1 i IINSERT.LON, AND, RE T.RLEN AL. . polo ba Ld 
vii | HPERLESRANSEQ,. .. RETRIEVAL 6 RANDOM AND, SEQUENTIAL, | a oid 
fy OAREA|=NEWRECD,. L/D, AREA IN, MAIN, ST ORAM | 
ieee i el Sey Woes pe Gt el Ya MOR KLi= -LABDOR,. . ota WORK. AREA, FUR, . INSERTION. tetova br wad al aa 
[an ree oe Oe oO OO LDAREAZ=0 DLDREG,: 1:1. BATRA! L/D. AREA. TO. SPEED, PROCESS, aoa LPG iia | 
fa ee oes oe ee ae fici| IRECFEORMAVARBLK,: 1. RECORDS, ARE, VARIABLE! AND, BLBCKIED 1.1 Moat 
Se ee ee ore fs ee ee KEMLEN= 25.) 0 0.5011 i tKEY, 0S, 2.5, BYTES) BONG oda baad atl 
et ke EYLDC A155) 1. _IL5| BYTES, OF, RECORD PRECEDE KEY Lk 
Fe ony Cael ges end Oe dad dos KEVYARG=SEARCKEY 5. i tIKKET 1S SEARCKEN FOR RANDOM RETIRDENVALM) 1. 1 
See Ce ee ed aes ora ERRORZERREX,. . ala... BWA UERROR, @D 10, ERREX. ROUTINE. 3b oo WY ra 
ded dasdleasad i. 4 NERDY aYESi... 11.11 IPARLTY, CHECK DE WRITE. ORDERS, LS, Td | raid 
Ri pb feb da, ce ob BE: PBREDRMED oi de bac ba ad p ald 


11.5. IMPERATIVE MACROS FOR ISAM FILES 


To process your ISAM files, you will issue imperative macros in your BAL program to 
communicate with OS/3 data management. These imperative macros expand as inline 
executable code to set up linkages, pass required parameters, and Initiate transfer of 
control to the:various ISAM transients and logic modules. 


pets As explained in further detail in 11. 7 and Appendix B, data management sets a flag in a 4- 
WY byte addressable field in your DTF file table (labelled filenameC), after the execution of 
each imperative macro you issue, to inform you of. the normal completion of the 
processing you have specified or of error or exceptional conditions. If you do not provide 
an error/exception handler routine, it is your responsibility to interrogate filenameC after 
each inline return and to take appropriate action in your program. ae 


spe 


Certain of these imperative macros also provide other useful information to you, in 
different fields of the DTF file table (filenameH, filenameP, and so on). These actions are 
polnteers out in the individual macro Cre and also recapitulated in 11.7. 


The peentivE macro descriptions are grouped according to the file processing functions 
involved: 


# = Basic macroinstructions: OPEN and CLOSE 

= File loading and extending macros: SETFL: WRITE, NEWKEY: and ENDFL 

# Random processing macros: READ, KEY; READ, ID; WRITE, KEY; UPDT; and WAITF 
m Record insertion macros: WRITE, NEWKEY; ADD; and WAITF 


m Sequential processing macros: SETL, GET, PUT, and ESETL 





11.5.1. Basic Macroinstructions 


You must use the OPEN and CLOSE macroinstructions to initiate and terminate action on 
an ISAM file. They call transient routines into main storage to perform the necessary 
preparation and close-out. The OPEN macroinstruction must be issued before any other 
macro function can be performed. 
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OPEN . Ce 


11.5.1.1. Initializing an ISAM File (OPEN) 


Format: 


-A OPERATION A 





OPERAND 





7 [name] - | 
. (1) 


te — 
1 


Positional Parameter 1: 


filename aH aan ; ; ; 
Is the label of the corresponding DTFIS declarative macroinstruction in the 
program. The maximum number of file names is 16. 


(1) or 1 E . 7 | C 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. - . = : | 
Examples: 
"LABEL AOPERATIONA ‘ | OPERAND | = 3 OR 
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CLOSE 


11.5.1.2. Terminating an ISAM File (CLOSE) 


Function: 


You must use the CLOSE macroinstruction to terminate processing of your file. The 
CLOSE macroinstruction calls on a transient routine that performs required 
termination operations, such as updating the format 2 label. Once your file is closed, 
no other macroinstructions can be executed for the file until it is reopened by the 


OPEN macroinstruction. 


Format: 








A OPERATION A OPERAND_ 





filename-1 [,...,filename-n] 
(1) 

1. 
*ALL 


[name] 


Positional Parameter 1: 
filename | | Oo 3.) ok | ya 3 | 
Is the label of the corresponding DTFIS declarative macroinstructio> © your 
program. The maximum number of file names is 16. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


*ALL 
Specifies that all files currently open in the job step are to be closed. 


Example: 


LABEL AOPERATIONA OPERAND A 


acetgoorsss 
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Programming Considerations: 


When you have issued a CLOSE macro, you may access filenameS, if desired, to 
ascertain the number of bytes required to hold the top index in main storage (11.6.2). 


11.5.2. Loading and Extending an ISAM File 


Whether a new ISAM file is to be loaded (created) or an existing one is to be extended by 
adding records at the end, the file processing functions are the same. Both functions are 
indicated in the DTFIS declarative macroinstruction when you specify, lIOROUT=LOAD. 
Records for the file are supplied in a work area to be blocked by data management. 


The imperative macroinstructions you require are the same in either case. The two 
processing functions are differentiated by the disk format 2 label. Once a file has been 
loaded successfully and a CLOSE macroinstruction has been executed for it, subsequent 


processing of a file for which you have specified IOROUT=LOAD extends, rather than 
creates, the file. 


The three imperative macroinstructions. are: 

= SETFL, which initiates the processing sequence: 

@ WRITE, NEWKEY, which loads a record to the file; and 

a ENDFL, Which terminates the secessing sequence. 

You do not follow the WRITE, NEWKEY macro with the WAITF macro for a load operation, 


although the WAITF macro is required after all other uses of the WRITE macro and all 
uses of the READ macro in eich ISAM. 
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SETFL 


11.5.2.1. Initiating the Load: Sequence (SETFL) 


Function: 


~The SETEL (set file load) macroinstruction calls on a transient routine which sets up 
controls in the DTFIS file table- qua in the indexes on the disk to prepare file for 


ia papi (or mending): 


Format: 


OPERAND 


- (filename ) ae 
0 


A OPERATION A 





Positional Parameter 1: 


ce 


= filename 
Is the label of the corresponding DTFIS file table in your program. 


(1)or1 a ee eer 
Indicates that you fave taeobeed fegistar 1 with the address of the DTFIS file 
table. 

Example: 
LABEL AOPERATIONA OPERAND he 
1 6 


UP-8068 Rev. 4 - SPERRY UNIVAC OS/3 - 11-28 
BASIC DATA. MANAGEMENT 


WRITE, NEWKEY 


11.5.2.2. Writing Initial Records to the File (WRITE, NEWKEY) 


Function: 


_ The WRITE, NEWKEY macroinstruction (that is, WRITE is the operation code, and 

NEWKEY. is positional parameter 2) writes a logical record to a file being loaded or 
extended. Specifically, it transfers a record from the working storage area to the I/O 
area. Before issuing the WRITE, NEWKEY macroinstruction, you must have stored the 
logical record in the work area. 


Format: 





A OPERATION A OPERAND 





filename ) NEWKEY 
(1) 
1 


Positional Parameter 1: 


filename 
Is the label of the ee DTFIS declarative macroinstruction in the 
_ program. | oe ° 
(1) or 1 


Indicates that register 1 has been preloaded with the address of the DTFIS file 
table. 


nostuona) Catamneter 2: 


NEWKEY > aa 
Indicates that a new record is to be loaded into an ISAM. file. . 
Examples: 
LABEL ADPEHATIONA - -QPERAND = PARE ER 
6 


1 1 
| ore WRITE EMPLMST,., NE EN eae er eee Bee 
bt | WROTE! C12. NEWKEN 
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Programming Considerations: 


The 


WRITE, NEWKEY macroinstruction causes the following actions: 


The key in the work area is checked against the key of the last record transferred 
into the I/O area, and if it is not greater, either a duplicate key or a sequence 
check error has occurred. Data management sets the appropriate flag in the 
filenameC field of the DTFIS file table and returns control to your error-handling © 
routine, if you have one, or to you inline. The record in error is not transferred to 
the 1/O area, and you may resume normal processing with another valid logical 
record. ode ; 


The record and its key are transferred from the work area to the 1/O area. 
When the I/O area cannot accommodate the entire record, a block is written into 


the prime data area on the disk, and the given record is used to start the next 
block. 


~ When a block’ is written, a key-pointer entry is forthed for the block index, 


provided that you have specified an indexed file. For an ASAM file 
(INDEXED=NO), this action is omitted. ot | 


Following execution of the WRITE, NEWKEY macroinstruction, the disk address of 
the logical record is available to you in a DTFIS addressable field labeled 
filenameH. You may save these addresses during load and present them later for 
direct accessing. A 3-byte count of the total number of logical records in the 
prime data area (contained in filenameP of the DTFIS file table) is also available 
to you. 


You may not overwrite the dummy record at file start, which is not available to 
you for storing data. If you issue the WRITE, NEWKEY macro with a search key of 
all binary O’s in your KEYARG field (this being the key reserved for the dummy), 
error processing results. Data management sets the invalid /D error flag in 
filenameC, issues error message DM24 (INVALID REQUEST (ID) — OUTSIDE FILE 
LIMITS), and branches to your ERROR routine. Refer to Appendix B. 


Examples: 


LABEL AOPERATIONA OPERAND A 
: 46 | . 


1 
Hoot, | Were lem mst, NEWKE 


eee 
2. wee.net [61> MeWwKEeY 


Assuming register 1 has been preloaded with the EMPLMST address, and the 
WRITE, NEWKEY macroinstruction has been executed successfully, the field in 
the DTDIS file table labeled EMPLMSTH holds the logical record address. 


If an error or warning condition has occurred, the field in the DTFIS file table 
labeled EMPLMSTC contains an indication of this condition. 
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ENDFL | ere  ¢ 


11.5.2.3. Terminating the Load Sequence (ENDFL) 

Function: a 
The ENDFL (end file load) macroinstruction calls on a transient routine that 
terminates your file loading or extending functions for the file and writes the final 
block on the disk. Also, file parameters are fested and any heauited index processing 


is performed. 


Format: 
LABEL A OPERATION A OPERAND 


filename . 
(1) 


7 [name] 





Positional Parameter 1: 


fie, 
f \ 


filename 
‘Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. | | 
Example: 
LABEL AOPERATIONA OPERAND A 


1 
eet le eel eee 
Ce nLePBxtoec| amc mar: 
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11.5.3. Inserting New Records in an ISAM File 


Once an ISAM file has been created, you can add new records to the file, providing that 
you allocated overflow space on disk during load. Each new record is placed in the 
overflow area and chained into logical sequence. You specify this file processing function 
by specifying IOROUT=ADD (or I|OROUT=ADDRITR, if retrieval is also desired) in the DTFIS 
declarative macroinstruction and use either the ADD or the WRITE,NEWKEY uoperaiye 
macro to add each new record. 


You supply new:records in a work area;,as you did during file creation. However, keys of 
added records need not be in ascending sequence. For ASAM files, the area specified by 
the KEYARG keyword parameter must contain the address of the record from which the 
current item is to. be chained. The DTFIS. keyword parameters must be equated to the 
same specifications as when the original file was created. . 


You issue the imperative macroinstructions WRITE, NEWKEY (or ADD) and WAITF to add 
records to an ISAM file. The form of the WRITE, NEWKEY macroinstruction for adding to a 
file is the same as you use for loading or extending a file, although the functions 
performed are different. fue 4 


In ISAM, there is no vpoenuelan preventing the adding of records with keys lower than the 
key of the first record loaded, except the key of all binary zeros. ISAM has begun the file 
with a dummy record having this key; so error processing will result if you attempt to add 
a record whose key is binary O. This is described under the WRITE, NEWKEY macro 
description in 11.5.2.2. : , oe 
In the course. of adding records to a file, overflow areas may become filled. After each 
WAITF macroinstruction, the conditions are reflected in the. program-addressable fields in 
the DTFIS file table. These fields are as follows: 7 a a 7 
# FilenameA 
A. 2. ne field jadicating the Runbes of prime data vinden having full evladee 
overflow areas. This field is set to zero if you. have not. specified cylinder overflow 
with the PCYLOFL keyword. 
a FilenameO 
A 2-byte field indicating the total number of overflow records. 
s FilenameP 


A 3-byte field indicates the total number of prime data records in the file. 
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WRITE, NEWKEY 


11.5.3.1. Adding a New Record to Overflow in an Existing File (WRITE, NEWKEY) 
Function: 


When you specify IOROUT=ADD or IOROUT=ADDRTR, the WRITE, NEWKEY 
macroinstruction logically inserts a new record in an existing file. You cannot use this 
macroinstruction unless you have allocated cylinder overflow area during load with 
the PCYLOFL keyword (11.4.12). Before issuing the WRITE, NEWKEY 
macroinstruction, you must have stored the logical record in the working storage area 
in the logical record format. 


‘In Feeponse to this macroinstruction, data management does the following 
1. Searches through the index to locate the record’s prime data block. This block or 
the overflow chain is then searched to determine the position into which oe 
“new record should: be Sate: | | 
2, Places the new record in overflow. 
3. Installs chaining in the blocks as necessary to maintain logical sequence. 
‘For ASAM files, the-index search is replaced by a direct-access to the proper block; 
you provide data management with the 5-byte file-relative address of the record from 
which the new record is to be chained by loading it into the KEYARG field before 
issuing the WRITE, NEWKEY macro (11.4.9). 
To ensure that all the actions initiated by the WRITE, NEWKEY macroinstruction have 
been completed, you must execute a WAITF macroinstruction. When control is 
~ returned to you from the latter, the work area: is: available for further insert records. 


The record just inserted is no longer in WORK1. 


Format: 


A OPERATION A OPERAND 


{ filename) ,NEWKEY 
(1) 
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Positional Parameter 1: 


Oa, 


filename 
Is the label of the corresponding DTFIS declarative macro in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


Positional Parameter 2: 


_NEWKEY 
Indicates that a new record is to be written into an ISAM file. 
Examples: 
LABEL ae eo -OPERAND A A 


[ema PLMAT., NEMICES 
Pot | WRETEL (O12 NEWKE 


Programming Considerations: 


a, lf an error or warning condition has occurred, the field in the DTFIS file table labeled 
EMPLMSTC will contain an indication of the condition. 
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ADD 


11.5.3.2. Adding a New Record to Overflow in an Existing File (ADD) | 
Function: 


The ADD imperative macro, exactly equivalent to the WRITE,; NEWKEY macro used 
when IOROUT=ADD or IOROUT=ADDRTR is specified, adds a new record to the 
overflow area of an existing et or ASAM file and chains it : into the appropriate 
logical sequence. 


As with the WRITE, NEWKEY macro, you must have previously provided an overflow 
area with the PCYLOFL keyword (11.4.12) when you originally created the file, and 

~ you must specify the IOROUT keyword. as just stated. You store the logical record in 
the work area before you issue the ADD macro, and you issue a WAITF macro after it, 
before issuing another function to the file. | 


If your file is an ASAM file, the ADD macro does not conduct.a search on key but 
directly accesses the data block (prime or overflow) containing the record from which 
the new one is to be chained. You provide data management with the 5-byte file- 
relative address of this record by loading it into the KEYARG field before issuing the 
ADD macro (11.4.9). 


Format: 
LABEL A OPERATION A OPERAND 


filename 
| 
1 


[name] 





Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS declarative macro in your program. 


(1) or 1 


Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


we 
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_ WAITF. 


11.5.3.3. Ensuring Completion of Record Transfer (WAITF). 
Function: 


The WAITF. macroinstruction ensures that the. transfer of a record between main 
storage and disk has been completed. It must be issued after you issue one of the 
following macros and. before you attempt to process another record: ADD; 
WRITE,NEWKEY; READ,ID; READ,KEY; or WRITE,KEY. Any exceptional (error or status) 
conditions detected during the execution of the WAITF instruction are reflected in the 
DTFIS filenameC field when control is returned to yeu . 


Format: 








‘LABEL 








= OPERATION A OPERAND . 





ee) 


Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 
Indicates that you have preloaded psaietey 1 with the address of the DTFIS file 
table. . 
Example: 
LABEL AOPERATIONA FP OPERAND oa Be 
10 


Po, | Warr lempe mss, 
11.5.4, Processing an ISAM File Randomly | 
You can retrieve individual logical records in random order for processing and updating. 
The record to be retrieved from the file is designated by its key or address and, in the case 


of an updating operation, is written back into the file. 


You indicate the random retrieval (and updating) file processing function in the DTFIS 


-macroinstruction by specifying IOROUT=RETRVE (or IOROUT=ADDRTR if new record 


insertions are also to be performed), and TYPEFLE=RANDOM (or TYPEFLE=RANSEQ if 
sequential processing functions are also to be performed). -— 7 


The following imperative macroinstructions are used in the random processing of an ISAM 
file: READ, ID; READ, KEY; UPDT; WRITE, KEY; and WAITF. 
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READ, ID i 
READ, KEY 


11.5.4.1. Retrieving a Record (READ, ID and READ, KEY) 


Function: 


The READ macroinstruction initiates the retrieval of a single logical record from an 

ISAM file. Before issuing the instruction, you must have stored the key-or the address 

of the record to be retrieved in the main storage area equated to the KEVARG 
_ keyword parameter of the DTFIS declarative macroinstruction. 


For indexed files, data managempnruses the argument for an | iaidexed search and 
retrieval of a record with a matching key. ASAM files treat the argument as a relative 
address and retrieve the block and record. If a work area has been specified in the 
DTFIS macroinstruction, the logical record is transferred to the work area designated. 
lf the IOREG keyword parameter is used, the address of the first character of the 
logical record is placed in the genta Fegister specified by nee: 


To ensure that the retrieval éeration has been completed, you must execute a WAITF 
macroinstruction before attempting to access the logical record retrieved. 


Format: 
LABEL “AOPERATIONA =| | OPERAND | 


on {kev} 
1 


[name] 





Positional Parameter 1: 
filename. | 
Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 


Indicates that you have preloaded register 1 with the addres of the DTFIS file 
table. 


Positional Parameter 2: 


ID 
Indicates that random retrieval by location is performed. 


| Indicates that random retrieval by key is performed. ‘ 
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Examples: 


LABEL ee ee OPERAND A 
16 


rere rar PLMST,, 
Poi | acme Emr msr, 


Programming Considerations: 


When control is returned to you after execution of the WAITF macroinstruction, the 
logical record associated with the argument in the area specified by KEYARG is 
available in either the work area or the I/O area, depending upon the DTFIS 
macroinstruction specifications. If the record is available in the |/O area, the register 
specified by the IOREG keyword parameter contains the address of the first character 
of the logical record. The disk address of the physical record is available at the 
address EMPLMSTG in the DTFIS file table. Indications of any exceptional (status or 
error) conditions are available at EMPLMSTC. : 


The dummy record containing an all-zero key and inserted by data management at file 
start is not available for you to retrieve. If you issue the READ, ID macro with the 
address of the dummy specified in the KEYARG field (11.4.9), data management sets 
the invalid ID error flag in filenameC and issues error message DM24 (INVALID 
REQUEST (ID)—OUTSIDE FILE LIMITS). If you issue the READ, KEY macro with a key 
of all binary O’s specified in the KEYARG field, data management sets the record not 
found flag in filenameC and issues error message DM31 (RECORD NOT FOUND FOR 
RANDOM FUNCTION). In either case, control transfers to your ERROR routine if you 
have specified one; otherwise, errors return to you inline. Refer to Appendix B. 
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WRITE, KEY an Ge a ? 


11.5.4.2. Updating a Record (WRITE, KEY)” 


Function: 


The WRITE,KEY macroinstruction initiates rewriting (updating) of the ‘last record 
retrieved with a READ macroinstruction. You must not alter the key field or the record 


length field (for variable records) in.any way. 


Format: 





OPERAND — 





A OPERATION A 





LABEL 





[name] filename ) ‘KEY 
Positional Parameter i 7 - —_ Site, -tefg ced . 
filename | | ie 


_ Is the label of the corresponding DTFIS file table in your program. 
(1) or 1 | aes 
Indicates that you have preloaded register 1 with address of the DTFIS file table. 


Positional Parameter 2: 


KEY 
Indicates that the last record retrieved by a READ,KEY or READ,ID 


macroinstruction is to be rewritten in the file. 
Example: 


LABEL AOPERATIONA OPERAND 


soothe ia Se opty Mie fe a og et 
EMPL.MS.T, KX ae thet peat cel eee, 
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Programming Considerations: 


In response to a WRITE, KEY macroinstruction, the updated logical record from the 
work area is moved to the correct location in the |/O area, and the block is rewritten. 
lf the record is updated in the I/O area through the use of the IOREG keyword 
parameter, no move is required since the record is already in its correct location. 


You must use a WAITF macroinstruction following the WRITE macroinstruction to 
ensure completion of the rewrite function. When control returns to you after the 


_ execution of your WAITF macroinstruction, the logical record last retrieved by a READ, 


KEY or READ, ID -macroinstruction, as well as the block that contains it, will have 
been rewritten onto your disk file. Any indications of exceptional conditions (error or 
status) detected during. the write and wait operations are available to you at address 


__ EMPLMSTC in the DTFIS file table. 


If you have tagged the record for” deletion, according to your own conventions, you 
may increment the 2-byte tagged- -for-deletion field at address EMPLMSTT in the 
DTFIS file table either before or after the rewrite operation. This count is available for — 
the life of the file to help you decide when file reorganization is beneficial. 
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UPDT 


11.5.4.3. Updating Last Record Retrieved (UPDT) 
Function: | | 


You issue the UPDT imperative macro (which is exactly equivalent to the WRITE,KEY 
macro for updating randomly processed files).to rewrite to its original disk location in 
an ISAM or ASAM file the updated logical record last retrieved by a READ, ID or 

~READ,KEY macroinstruction. You do not use the ‘UPDT macro unless you have 
updated the record; in updating, you must neither alter the key nor change the length 
of the record. Like the WRITE,KEY macro, the UPDT macro must be followed by a 
WAITF macro before you issue another function to the file. 


Format: 





A OPERATION A OPERAND 





filename 
(1) 
1 





Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS declarative macro in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


11.5.5. Processing an ISAM File Sequentially 


You may also retrieve and update logical records sequentially. The first record to be 
retrieved may be designated by the beginning of the file, by a relative record disk address, 
by a specified key, or by any key greater than or equal to a specified value. The SETL 
macroinstruction specifies which kind of starting point is desired. Individual records are 
then retrieved in sequence by the GET macroinstruction. Where an updating operation is 
to be performed, the individual records are rewritten into the file by means of the PUT 
macroinstruction. 


You indicate the sequential retrieval (and updating) file processing function in the DTFIS 
declarative macro by equating the IOROUT keyword parameter to RETRVE (or to ADDRTR if 
new record insertions are also to be performed), and the TYPEFLE keyword parameter to 
SEQONTL (or to RANSEO if random processing functions are also to be performed). 


aa 
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To terminate a retrieval sequence, you issue an ESETL macroinstruction. This ensures that 
logical records committed to output by the PUT macroinstruction are written onto the disk. 
After the ESETL macroinstruction has been executed, another retrieval sequence may be 
initiated by executing a SETL macroinstruction. Also, if you have specified 
TYPEFLE=RANSEO in the DTFIS declarative macro, the READ,KEY; READ,ID; and 
WRITE,KEY macroinstructions may be issued, once you have terminated the sequential 
mode. 
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SETL ak Eta? Bs CPS | ” : mae e 


11.5.5.1. Initializing a Retrieval Sequence (SETL) 

Function: 
The SETL macroinstruction initializes a retrieval sequence. It specifies the file from 
which the records are to be retrieved and the point at which the retrieval is to start. 
For the starting point, the SETL macroinstruction can select the beginning of the file 
or other file locations. When control is returned to you from the SETL 
macroinstruction, the retrieval sequence may start. 


Format: 


LABEL A OPERATION A OPERAND 


[name] filename ; BOF 
(1) GKEY 
1 ID 
KEY 





Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


Positional Parameter 2: 


BOF 
Indicates that the retrieval sequence is to begin with the first logical record of 
the file. 


GKEY 
Indicates that the retrieval sequence is to start with the first logical record whose 
key is greater than or equal to the value in the area equated to the KEYARG 
keyword parameter of the applicable DTFIS macroinstruction. Used only for 
indexed files. 


Indicates that the retrieval sequence begins at the location given in the KEYARG 
keyword parameter in the applicable DTFIS macroinstruction. 


OF, 
ro 
: 
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KEY -_— 
Indicates that the area equated to the KEYARG keyword parameter in the 
applicable DTFIS macroinstruction holds the key of the first logical record to be 
retrieved. Used only for indexed files. 


Examples: 


LABEL Peotone OPERAND A 
16 


eerrE oe PL M8.T in GE: 
eit, | bere, | 


EMPILMST.. iKE 
Programming Considerations: 


When your file is an ASAM file, the KEY and GKEY peeeane parameters of the SETL 
macroinstruction should not be used. 


The dummy record inserted by ISAM at file start, whose key is all binary O's, is not 
- available for you. to retrieve. If you issue the SETL,BOF macro, -or issue the 
SETL,GKEY imperative macro with an all-zero key specified in the KEYARG field, 
ISAM. prepares to give you the first record after the dummy, and no error. process! ig 
results. ' 


On the other hand, if you issue the SETL,KEY macro with a search key of all binary 

~ O's specified, data management sets the record not found error flag in filenameC and 
issues error message DM31 (RECORD NOT FOUND FOR RANDOM FUNCTION). If you 
issue the SETL,GKEY macro and the search key specified is greater than the highest 
key in the file, DM32 (RECORD NOT FOUND FOR SEQUENTIAL FUNCTION) is issued. 
If you issue the SETL,ID macro with the address of the dummy record specified as a 
search argument, data management sets the /nva/id /D error flag and issues error 
message .DM24 (INVALID REQUEST (ID)—OUTSIDE FILE .LIMITS). Control is 
transferred in either case to your ERROR routine if you have Specified one; otherwise, 
to your program inline. Refer to Appendix B. 
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GET 


11.5.5.2. Retrieving Next Logical Record (GET) 
Function: 


The GET macroinstruction retrieves the next logical record in sequence. It must be 
part of a valid retrieval sequence initiated by a SETL macroinstruction. If the block 
containing the next logical record is not already in main storage, the GET instruction 
reads it into the I/O area designated by the DTFIS macroinstruction. The DTF 
parameters you specify indicate preference for one of the following two modes of 
handling the logical record: 


= By omitting the WORKS and IOREG keyword parameters, you choose to specify 
the work area that is to receive the logical record with every GET 
macroinstruction. 


= When you specify the WORKS and IOREG keyword parameters, you choose to 
process the record in the I/O buffer area. The value specified in the IOREG 
keyword parameter is the number of the general register that points to the 
record. 


- If the GET instruction requires the reading of a new block, and if a PUT 
macroinstruction was executed for any logical record in the previous block, then the 
previous block, as updated, is written back onto the disk before the new block is read. 


Format: 








A OPERATION A 









OPERAND 


filename : workname | 
eT 
1 0 






Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFIS file 
table. 


oe 


ee 
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Positional Parameter 2: 


workname 


Is the label of the work area into which the record is to be transferred. 


(0) or O 


Indicates that register O has been preloaded with the address of the io area 
into which the record is to be transferred. 


Positional parameter 2 is not required if the MWORSS? keyword of the eine declarative 
macro was sanarer to ce ee 


eanles: 


LABEL . ADEERATIONA | OPERAND . _ A 
16 


EMP.LM wEMRCD 


eo Hae fe T 


NY 


a The next ares reeord of EMPLSMST is Gaeiuad into the work ¢ area labeled 
-EMRCD. Any abnormal conditions. are indicated by the bit settings in addressable 


field at location EMPLMSTC: The disk address from which the logical record was 
transferred is available to you in the addressable field at location: EMPLMSTG. 


The register equated to the IOREG keyword parameter (for example, register 4) 
holds the address of the first character of the logical record. Addressable fields 


EMPLMSTC and EMPLMSTG have the same significance as in example 1. 
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PUT 


11 2: S. 3. mpceune a Record en, 
Eanations 


The PUT macroinstruction’ indicates that the last record retrieved by a’ GET 
macroinstruction has been updated and is to be rewritten on the disk. It must be part 
of a valid retrieval sequence initiated by a SETL macroinstruction and must follow a 
GET macroinstruction. Updating takes place in a sequential retrieval operation only 
through the execution of the PUT macroinstruction. If a record retrieved by a GET 
~instruction is not updated, there is not need to execute a PUT instruction. 

: The PUT macroinstruction-sets an indicator in the DTFIS file control table to ensure 
that a write is done before the present block is abandoned. The next block is not 
accessed until all logical records in the present block have been -processed. 


Like the GET macroinstruction, the PUT -macroinstruction has two forms: the form 
that uses a work area and the form that uses an |/O area. If the DTFIS 

*. macroinstruction has specified use of a work area, then the PUT. macroinstruction 

. «Must specify the address of that work area from. which an updated record will be 

_ transferred to:the 1/O area. This may be the same area specified-in the: preceding ( 
GET macroinstruction, or it may be a.different area. Under no circumstances may the 
original record length be changed oueing update Sper atans: nor may you alter the 
ie o the apace record.-.. :..0:-:. aS 


If you: have eaaaied the WORKS en eee of your - DTFIS 1 to NO, then you 
must also select a general register to be the current record pointer by specifying the 
IOREG keyword, and you will supply the address of the logical record in this register 
when you execute the previous GET macroinstruction. In this event, data 
management assumes that you udpated the record in the |/O area. 


Format: 
LABEL A OPERATION A OPERAND 


filename ; workname 
(1) (0) 
1 0 


[name] 
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Positional Parameter 1: 


filename 
Is the label of the corresponding DTFIS file table in your program. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the. DTFIS 
macroinstruction. 


as Parameter 2: 


: “wotkname 
ls the: label of the work area Hor which the orn is to be fediisterred: 


(O) or O 
Indicates that you have preloaded register O with the address of the werk area 
from which the record is to be transferred. 


Positional saeaietes 2 is not required if the WORKS Revers of the DTFIS declarative 
macro was equated to NO. 


Examples: 


f es j LABEL AOPERATIONA OPERAND A 
aed 10 16 2 nr 


eee | tae a 
Hoos iiy | Pur. | lempe msi, .CO0. 
ft po ee PLMST 


1. The juiesi record last retrieved from EMPLMST is feulacea by a record in the 
work area whose address is specified in register 0. An indicator in the DTFIS file 
control table is set to initiate rewriting of the block before the next record is read 
into the I/O area. 


2. The logical record, whose address was supplied in the register specified by the 
IOREG keyword “parameter when the preceding GET macroinstruction was 
executed, is assumed to have been updated: . 
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ESETL 


11.5.5.4. Terminating a Retrieval Sequence (ESETL) 


Function: 


The ESETL macroinstruction terminates a retrieval sequence initiated by a SETL 
macroinstruction. If there are any updated logical records that have not yet been 
rewritten, they are rewritten at this time. After the ESETL instruction has been 
executed, another retrieval sequence may be initiated by means of a SETL instruction. 


Format: 









A OPERATION A OPERAND 


[name] ESETL 


filename 
(1) 
1 


filename ma 
Is the label of the corresponding DTFIS file table. 


Positional Parameter 1: 


(1) or 1 
Indicates that you have preloaded the address of the DTFIS file table into register 
Examples: : 
LABEL AOPERATIONA OPERAND A 
" 6 : 


ite 0 16 
Poti. | eget empemar 
Pose | egerel [C1 


ype 
‘ 
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11.6. ERROR AND EXCEPTION HANDLING 


11.6.1. FilenameC 


Whether OS/3 data management detects certain errors or exceptions to file-processing 
performance, or it ascertains that the processing you requested was carried out exactly as 
specified, it makes appropriate entries in a 4-byte, full-word-aligned addressable field of 
the DTFIS. file table, designated filenameC. You address this field by concatenating the 
character “‘C’’ to your 7-character logical file name and may use the BAL test-under-mask 
(TM) instruction to ascertain its contents. a 


Each of the 32 bits in the 4-byte field filenameC has its own significance as a status or 
error flag. It is your responsibility to provide the coding for testing the bits of filenameC 
and for taking action appropriate to the condition reported. If you have provided an 
error/exception handling routine, data management returns control to this routine in all 
events other than successful, unexceptional performance of the requested function. (In the 
absence of such a routine, control invariably returns to you inline.) You can avoid the need 
to check filenameC at the inline return points by including the necessary coding in your 
error routine. Table B—3 in Appendix B gives the meaning of the bits in filenameC that 
are set by OS/3 ISAM for you. 


11.6.2. Other Addressable Fields of the DTFIS File Table 

The OS/3 ISAM- imperative macros also: provide other information to you, ‘in different 
fields of the DTFIS file:table. Most of these actions have been discussed in the previous 
paragraphs describing these imperatives. Table 11—4 summarizes the information 
provided in these fields and indicates the length of each field and whether it is half-word- 
aligned or full-word-aligned. The individual fields are addressed by concatenating the 


character in the left-hand column of the table to your 7-character file name. 


Table 11—4. Summary of Filename-Addressable Fields in DTFIS File Table (Part 1 of 2) 













Field 
Addressable 

by Suffix: ~ 
to Filename 


Cc 
H 









Content _Alignment Length, in Bytes. 









Number of cylinders with full overflow area _H 
- ie : F 


Error and Exception Conditions — see Appendix B 





Relative disc address from which the last record 
was retrieved ° ; Mes 





Relative disc address to which. the last record was U 
written 
U 





Total number of overflow records H 
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Table 11—4. Summary of Filename-Addressable Fields in DTFIS File Table (Part 2 of 2) . 4 


Field 
Addressable 

by Suffix 
to Filename | . 


Content Alignment Length, in Bytes 


Number of overflow records retrieved that. were not. . 
first in the chain 


Number of records your program has tagged for deletion 


- LEGEND: 





H_ Half-word aligned 
F Full-word aligned 
_U_ Unaligned 


11.7; PROGRAMMING EXAMPLE 


11.7.1. Sample ISAM File Load iia ae 


The following coding forms contain. a eeiaplere program for the initial foad - an jadexed a 


ISAM file, including the OS/3 job control statements you need to:assemble and execute it. one 


The logical name of the file-in the example is-‘AFILE."’.A note: may be in order about the 
boundary alignment of the storage areas and buffers shown in the example (REGS, WKSP, 
INDBUF, and DATABUF). The register save area, as you recall from 11.4.14, must be’ full- 
word-aligned eau and oe others need to ‘be aligned: on nals yore pOUncanies:: 


That they are so aligaedr in the ee without ‘hie fieual full- or halt word constants 
needing to be defined to skip bytes aneae of them and Aoree anne ts is the result of 
special circumstances: — 


# The first of these areas (REGS) immediately follows the DTF. 


= The OS/3 DTF generator automatically ensures that the DTF file apie is full- word- 
aligned. os 

# §The length of the DTF file table generated when you have e specified \OROUT= LOAD is 
332 bytes (11.3). 

This is enough to ensure that REGS is full-word aligned; its 72- -byte length and the even 

lengths of the other areas, in turn, cause them-to be properly. ws daaree ‘In the real world, of 

course, you. will seldom find circumstances so neat. 


(om 


en 
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Example: 
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12, IRAM Formats and 
File Conventions 


12.1. GENERAL 


The indexed random access method (IRAM), a fifth access method in OS/3 for handling 
disk files, is available for programs written in RPG Il language. RPG II programs compiled 
in the IBM System/3 mode automatically access all disk data files via IRAM; however, 
RPG II programs compiled in OS/3 native mode may advantageously specify the use of 
IRAM instead of other OS/3 disk access methods. 


The main: meadvantade in using IRAM in RPG i" is : the imnerent saving of main storage Only 
one of two IRAM processing modules is required: the smaller module (about 1350 bytes) 
provides random. and sequential functions for processing nonindexed IRAM files. The 
larger module (about 2050 bytes) provides the same functions: and also keyed functions for 
random and sequential proces stg of IRAM files created with indexes. 


Thi functionality Sjovided: ‘by IRAM. is equivalent to that iievided by 0S/3 ISAM and 
ASAM, and by the OS/3 nonindexed access disk methods, SAM and DAM (relative record 
addressing); however, these modules are considerably larger than those of IRAM. It is also 
equivalent to that provided for sequential, direct, and indexed files processed with RPG Il 
programs under IBM System/3. IRAM files may reside on any of the disk subsystems used 
with OS/3. An IRAM file may occupy from one to eight disk packs, which must be of the 
same type. 


The IRAM processor can access only disk files it has created or files created by the 
MIRAM processor that have IRAM characteristics. It cannot. access.disk files that have 
been created by the OS/3 ISAM, ASAM, DAM, or SAM access methods, nor can IRAM 
files be processed by these access methods. IRAM files can be processed using the OS/3 
independent sort/merge program, however, and by the data utilities program. RPG II users 
converting to OS/3 from IBM System/3, moreover, may. transcribe existing data files to 
IRAM format by using procedures. detailed in the System/3 to OS/3 transition user 
guide/programmer reference, UP-8379 (current version). 


12.1.1. IRAM Concepts 
A apne! of features and concepts distinguish IRAM Poin other disk access methods: 


= Data records in IRAM fies are a nitorna; fixed size and may span physical Blocks 
and sectors, tracks, and even cylinders as required. They may extend from one 
volume onto another (unless the file is created for processing only a single volume at 
a time). 
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# Data records are written on disk compactly, as a continuous string of bytes, without 
any space in the string being used for system control or overhead. The data string is 
. enlarged only by appending records. 


# The string of data records is always usable in sequential and direct access modes, 
with direct access being made by a file-relative record number. Moreover, the data 
can be specified to be indexed by key; this causes IRAM to build a suitable index 
structure that resides in a second partition, separately from the data. 


# An indexed IRAM file can be referenced by the additional modes of random-by-key 
and sequential-by-key. 


# Indexed IRAM files, multivolume or single-volume, may be created by means of an_ 
orderly load (records submitted in ascending order of keys) or a disorderly load (record 
keys in no particular order), and they may be extended by appending records in either 
‘manner. If orderly load or extend: is specified, automatic sequence checking is 
Late! and results | in immediate Fejechen of any necord wie an out- of-sequence 


a Duplicate keys are not permitted; a record with a key duplicating one already in the 
file is rejected immediately. IRAM does not sort the index at the completion of a 

meres load, but maintains the index current on a- PuGCOl ae “record Base 
ae When a new. Beara nae been added to an "indexed or ‘noniridexed IRAM file, it is 
- immediately. pyauanle) for retrieval. a Sy 


# Multivolume IRAM files. may be siealed for processing with either one volume online 
at a time, or with all volumes online: mney must be processed in the same manner as 
Cheated BAe ngs I is 
a All programs accessing ‘an RAM file Bead not use the same data Butter size for |/O 
as was. used to create the file. However, all those accessing an: indexed IRAM file 
must use the same index. buffer size (unless they are not issuing keyed functions).. 
= IRAM's restrictions are the following: 
co ns RECOMNS ate Hned longi: 


Se Duplicate keys are. rejected in indexed files. 


= The. maximum Kay length is 80 bytes (RPG Il allows only 29 ree however) No 
_byte of a record key may contain the: hexadecimal value ‘FF’. 


— The minimum size for the index buffer is 256 bytes. 


— No IRAM function is provided for deleting records — logical deletion and physical 
Temneval: are 2 FesponsiDiitles of the user's progam, 


The fsliawine: =ubeectané describe the IRAM record and file formats and conventions and 
ane Epi peeSsig oF ieee direct, and indexed IRAM files. . : . 
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12.2. IRAM FILE CONVENTIONS AND FORMATS 


A nonindexed IRAM file contains only one partition, the data partition, which IRAM defines 
to the system access technique (SAT) as containing 256-byte physical blocks, unkeyed. An 
indexed file, on the other -hand, contains yet a second partition, the index partition, 
specified to SAT as containing 256-byte keyed blocks. The data partition of an indexed 
IRAM file is laid out exactly like that in a nonindexed file; it precedes the index partition, 
which begins on a separate cylinder from it.) 


12.2.1. The Data Partition 


The data partition, cylinder aligned, consists of a single, compact string of data records, 
spanning the sector or physical block boundaries as necessitated by their uniform, fixed 
lengths. Records may be keyed or unkeyed; they contain no bytes reserved for control 
overload, nor are there any such nondata bytes in the string. Figure 12—1 shows the 
appearance of IRAM data records and lists the rules for their structure. 


When these data records are stored in an IRAM file, the records are loaded consecutively, 
arranged in the same order as you originally presented them to the IRAM processor. 
Although the records are stored in 256-byte sectors on your fixed-sector disk packs, and in 
256-byte physical blocks on variable-sector disks, the data records may span these 
physical boundaries. Record-length and sector-length need not coincide, as shown in 
Figure 12—2. Your data records are also independent of track boundaries, cylinder 
boundaries, and even volume boundaries (except when a multivolume file is created for 
single-volume processing). The data partition of your IRAM file is a long continuous string 
of data records. When new records are added, they are appended to the string, that is, 
added at the end as a continuation of the Crain Sting of records. 


12.2.2. Entries in the Index Partition 


As it loads your keyed records into the data partition of an indexed file, IRAM extracts the 
key from each record and constructs a 3-byte pointer from.the file-relative record number 
of the position to which the record is written. From these it forms an index entry for each 
record, and stores the entry in the index partition. The index entry for each record is then 
equal to the specified key length plus three bytes; it is stored in what is called the fine 
level of He Lgl index. 


The fine level of index is not formatted for hardware search, unlike the other levels of 
index described in subsequent paragraphs. It is treated as a chain of multisector blocks 
(each sector being 256 bytes long, as previously stated). Initially, each fine-level index 
block is only partly filled (to just beyond the three-quarter level) with index entries so as to 
permit later insertion of new entries, as required. All entries :in the fine-level index are 
maintained in ascending key order. Figure 12—3 represents a fine-level index block 
comprising three 256-byte sectors. 
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Without Key 





Key at Head of Record 





Key Internal to Record 





LEGEND: 


Record key. All keys in a keyed file must have the same length; each record in a keyed file must have one 
unique key; and the starting location of the key must be the same in each record. You specify the length of the 
key, which may range from a minimum length of 3 bytes to a maximum of 80. (The maximum key length for 
RPG II records is 29 bytes.) No byte of any key may contain the hexadecimal value ‘FF’. 


Key location. The starting location of the key must be the same in each record. You may specify the number of 
bytes of data preceding the key. If you default, IRAM assumes the key starts in the first byte of the record. 


Data portion. of your logical record 


Length of logical record (key plus data). You specify this length, measured in bytes. All records in an IRAM file 
must have the same length. » ; : i 


Figure 12—1. IRAM Data Records with and without Keys 


aun 
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aa . EXAMPLE 1 


SECTOR 1 | ~  SECTOR2 “SECTOR 3 









EXAMPLE 2 


SECTOR1 ae SECTOR 2 


SECTOR 3 






EXAMPLE 3 
SECTOR 1 SECTOR 2 ; SECTOR 3 
\ NOTES: 


All sectors equal 256 bytes. 

Records in example 1 equal approximately 190 bytes each. 
Records in example 2.equal approximately 300 bytes each. 
Records in example 3 equal approximately 70 bytes each. 


Figure 12—2. IRAM Data Records Spanning Disk Sectors on a Fixed Sector Disk | 


CHAIN TO NEXT 
FINE BLOCK 


FLAG BYTE 








CURRENT NUMBER OF ACTIVE BYTES ——\ 
* ’ ; , — e 2 
CONTROL AREA | 
IS LAST SIX pacar 
BYTESOFINDEX( =... 
BLOCK. 
~ a \ 


INACTIVE AREA: 
ACTIVE ENTRIES - . : 


CONTROL AREA 


Figure 12—3. Typical Fine-level Index Block of Three Sectors 
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One other hierarchic level of index is always created: the coarse-level index. This is 
hardware searchable and comprises 256-byte blocks, each containing a variable number of 
entries similar to those at the fine’ level. One difference, however, is that the 3-byte 
pointer in each coarse-level entry does not represent the file-relative number of a record 
in the data partition; it points to another index block at a lower level — either a fine-level 
index block, or a block in what is called the mid-level index. Another difference is that, 
instead of containing a 6-byte control area, each coarse-level block uses its final byte to 
indicate the number of bytes in the block that represent active entries. The index entries in 
a coarse-level block are filed in descending order of key values, the high key of the block 
being the first encountered by the hardware search. Mid-level index blocks have the same 
construction as those in the coarse level; refer to Figure 12—4. The mid-level index is 
created by IRAM as required; the process is described in the following subsection. 


ACTIVE ENTRIES INACTIVE AREA’ 


SECTOR 





Figure 12—4. Typical Coarse- or Mid-Level Index Sector 


12.2.3. Structure of IRAM Index 


When the IRAM processor builds an index for your file, it creates at least two levels of 
index: a fine level and a coarse level. If your file is very large, one or more mid-levels of 
index are created as they are needed. 


The fine level of index consists of an entry for every record in the data partition of your 
file. The fine-level entries are filed in ascending key order until an index block (256 bytes) 
is filled. At this time, one coarse-level entry is made that points to the high key entry in 
that filled fine-level block. As each fine-level block is:filled, another coarse-level entry is 
made. This pattern is continued until all your records are on file. 


The coarse-level index is arbitrarily allocated by IRAM; its size is disk-dependent. On the 
fixed-sector 8415, 8416, and 8418 disks, IRAM allocates two tracks; on the variable-sector 
8411, 8414, 8424, 8425, 8430, and 8433 disks, it allocates four. If the coarse-level index 
is filled before all your records are on file, a mid-level index is created. The IRAM 
processor allocates a new track, designates it as a mid-level index, and copies three- 
quarters of the entries from the filled coarse-level track onto this mid-level track. The 
IRAM processor creates a new entry in the coarse-level index that points to the high key 
of a block in the mid-level. In this manner, three-quarters of a track on the coarse-level 
index are replaced by a single entry. | 


As new fine-level entries are recorded, one entry is made in the coarse-level index for 
each filled index block in the fine level, just as before. When the coarse-level track is filled 
again, another mid-level track is allocated, three-quarters of the coarse-level entries on 
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‘that track are moved into. the mid-level index: track,and one new. coarse-level ‘entry is 
created to-point. to the high key of the second track. of the mid-level index. This process 
can be repeated until each entry in the coarse-level index points to the high key of a track 
in the mid-level index. Figure 12—5 illustrates the structure of an IRAM index. 


oa — _ | 4 TRACKS 
COARSE LEVEL - | (2 TRACKS ON 
He ee 3 8416 AND 8418 DISCS) 


MID-LEVEL ~*~ | ADD 1 TRACK AT 
(IF NECESSARY) - A TIME; AS NEEDED... 


ONE ENTRY FOR 
EVERY RECORD IN 
DATA PARTITION 


FINE LEVEL 





Figure 12—5. IRAM Index Partition 


At this point, “the addition of new records would cause another mid-level index to be 
created between the filled coarse-level index and the old mid-level index. A search for a 
specific data record by S18 in a 4- level index would proceed as follows (refer to Figure 
A2—6).. 


= the search begins in the desis. 
# a hit is made that points to the Now midleval index; 
” the new mid-level is searched: 
a a hit is made that points to the-old. mid-level index;. - 
a | the old mid-level is searchiad: a | 
= a hit is made that points to the fine-level index; 
ee 
. _ the fine- level. is searched; ce 


=a hit is: ‘made » which: points: to the data record in 1 question: and 


the data peeoc: is retrieved. §8.. ©... ..- 
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-It is not likely that your file would'be large enough to require more than three index levels, 
but IRAM can create an index for any size file up to ane physical limitation o eight disk 
devices. 


See ae 
| __-_ 
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Figure 12—6. Typical Search of 4-Level IRAM Index 
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12.2.4. Estimating Disk Space Required for an Indexed IRAM File 


To estimate the number of cylinders for your primary allocation of disk space to an indexed 
IRAM file, follow the straightforward procedure outlined herein. The result is a good first- 
level approximation for your use in specifying the EXT statement in the job control device 
assignment set that is used in allocating disk space for an indexed IRAM file to be created 
by your program. The same calculations may also be used for specifying the number of 
cylinders to be allocated for an indexed IRAM file to be generated from another file by the 
OS/3 data utility program (as in the task of metre ns eHiping you! data files in the System/3- 
to-OS/3 transition process). 


The number of evlinders required for an indexed IRAM file includes those occupied by the 
data partition and the index partition; the latter comprises the fine-level index and the top 
levels of index (the coarse-level and the mid-level, if any). Your initial space allocation for 
an indexed IRAM file must always be at least two cylinders because the data partition and 
the index partition are separate, and each is cylinder-aligned. To obtain the approximate 
size of the space the file will occupy, proceed as follows. 


First, calculate D, the number of 256-byte sectors required for your data records: 
record-length - number-of-records (1) 
256 


Next, calculate B, the number of index blocks required by your fine-level index: 


number-of-records - (keylength + 3) | (=| (2) 
B —_ i ee a 


(256 - m) — 6 3 


where: 


the factor 4/3 is used because the average fine-level index will be 3/4 full. m is the 
number of 256-byte sectors in the index buffer. (See q 3.2.1.) 


Next, calculate F, the number of 256-byte sectors required by your fine-level index: 
F=m-:B 7m . | (3) 

NOTE: 

Over 95 percent of the file allocation is used by the sum of the data requirements (D) and 

the fine-level requirements (F). Unless you need a more accurate estimate, skip the 

calculations to obtain the number of 256-byte sectors required for the coarse level (T) and 

the mid-levels (S) of the index, and do your final calculation as described in step 6 with T 


and §S set to zero. 


Next, do the following calculations to obtain the number of 256-byte sectors required for 
the top levels of the index — the coarse-level, T, and the mid-level, S. 
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The coarse-level calculation is automatic: IRAM always sets aside two tracks of coarse- 
level index for an indexed IRAM file that resides on an 8416 or 8418 fixed-sector disk; it 
sets aside four tracks for a file on a-variable-sector disk (8411, 8414, 8430, or 8433). The 
number of sectors these tracks contain are found in column T of Table. 12—1. If they can 
contain enough index entries to point to all your fine-level index blocks, no mid-level index 
is needed. . 


On the other hand, if the number of fine-level index blocks exceeds what the maximum 

coarse-level index can control, IRAM automatically creates one or more tracks of mid-level 

index, one at a time, as it finds the need to control the remainder.. You may proceed as 

follows to calculate the number of sectors these mid-level index tracks will contain: 

= Take (from Table 12—1) the value T, which represents the number of sectors 
allocated to the coarse-level index for a file on the type of disk this index is to reside 


on, calculate E, the number of index entries that T can contain, and compare this 
number to B: . rae 


255 : 
E= Eaecerersd | (4) 
(keylength+3) . 


where: 
[ ] implies the integer value only: no remainder. 


If E is equal to or greater than B, no mid-level index is required. The value S (the 
number of sectors required for the mid-level) in step 6 is set to zero. 


= On the other hand, if E is less than B, a mid-level index will be constructed; proceed 
to calculate S, the number of sectors it will contain: 


S = B= (2) (5) 


| 255 | 
keylength + 3 
where: 


The factor of 4/3 is used because the average mid-level index will be 3/4 full. 


The final calculation of the number of cylinders to allocate to the whole file is represented 
by the following formula: 


(F+T+S) DO (By: 
U-:N A-N 
where: 
Cc 
Is the number of disk cylinders to allocate to the indexed IRAM file. 
A 


Is the disk dependent number of 256-byte sectors per track (data partition) from 
Table 12—1. 


"Nenana ‘ 
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D ng 
Is the number of 256-byte sectors required for the data partition. 
: 
Is the number of 256-byte sectors required by the fine-level index. 
Is the disk-dependent number of sectors allocated automatically for the coarse- 
level index, from Table 12-1. 
Is either zero (when no mid-level index is required), or the number of mid-level 
index sectors required. 
Is the disk-dependent number of 256-byte sectors per track, from Table 12-1. 
” i | 
Is the disk-dependent number of tracks per cylinder, from Table 12-1. 
Example: 


Given the following parameters, calculate the number of cylinders to allocate for an indexed 
IRAM file residing on an 8416 disk: 


Number of records: 77,500 
Record length: 512 bytes 

Key length: 28 bytes 

Index buffer length: 512 bytes . 


» OD 


I 


record-length - number of records eeAT) 
256 ate: 


= 5612 - 77,500 
256 


= 155,000 sectors for data partition. 


» B = number- of- records - (keylength+3) » ee (2) 
i (256-6 3 | ok 


= 77,500(28+3) - 4 
(256-2)-6 3 


= 6331 blocks for fine-level index. 
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»= F = m-B (3) 
=. 2% 6331 
= 12,662 sectors for fine-level index. 

m The coarse-level index for an IRAM file on an 8416 disk contains 80 sectors; by 
inspection this number can be seen to be too small to avoid. the. need of a mid-level 
index. 

# E = | 255 | -7T (4) 

(keylength+3) os 
= | 255 ] - 80 
(28+3) | 
= [8.22]: 80 = 8 - 80 = 640 index entries can be contained by T. 
» S = | B-E 4. oe 4 (5) 
lat s| 255 ia 3 
(keylength+3) 
= 6331-640 4 
8 3 
= 949 sectors for mid-level index. 
» C = (F+T+S) + _D | (6) 
U-N A-N 
= (12,662 + 80 + 949) +: «155,000 
40-7 40:7 
= 168,691 
280 
= 603 cylinders to be allocated for file. 
12.2.5. Estimating Disk Space Required for a Nonindexed IRAM File 


To estimate the number of cylinders to be allocated for an IRAM file created without an 
index, proceed to calculate D, the number of 256-byte sectors required for your data 
records, using formula 1 in the preceding subsection, and divide by the product of A times 
N (taken from Table 12-1): 


aN 7) 


en 
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Table 12—1. Disk-Dependent Factors for Calculating Size of Top-Level Index for an IRAM File 


U A T 
SPERRY UNIVAC (Number of 256-byte (Number of 256-byte (Number of sectors 
Disk Subsystem sectors per disk track sectors per disk track allocated to course- 
for index partition) for data partition) level index) 


N 
(Number of tracks 
per disk cylinder) 
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13. Functions and Operations 
of IRAM 


13.1. PROCESSING NONINDEXED IRAM FILES 


Nonindexed IRAM files are created with specific processing requirements in mind. A 
sequential nonindexed file is one in which the physical, consecutive order of records on 
disk is of specific significance to your application, and you expect to process these records 
one after the other. A direct nonindexed file, on the other hand, is one arranged on disk so 
as to provide ready access to a specific record without processing any of the records 
preceding it. The consecutive, physical order of records in the direct file is usually of less 
importance than your ability to access each record at random, independently of any other 
record in the file. — 


A capability that sets IRAM off from other disk access methods, however, is that record 
retrieval, update, and other operations on nonindexed files may be _ performed 
consecutively or randomly, regardless of the primary purposes for which files were 
created. The direct file created randomly by relative record number has several special 
characteristics that need separate consideration; for this. reason, the processing 
procedures for the randomly processed and sequentially processed consecutive file are 
taken up separately in the following paragraphs. 


Nonindexed IRAM files spanning two or more volumes may be created with only one 
volume mounted at a time, or with all volumes mounted. They must always be processed 
in the same way as they were created: only one volume online, or all online.* However, it 
is important to realize that the nonindexed multivolume file intended for single-volume 
processing may not be created randomly by relative record number, nor may it be 
processed this way. Multivolume files for which relative record addressing is planned must 
have all volumes mounted — whether they are sequentially. processed or randomly 
processed consecutive files. 


All IRAM files may be processed with a randomly- ordered disk file that contains relative 
record addresses; this type of file is known to the RPG I programmer as a tag, or 
ADDROUT, file. You may create such a file from an IRAM file by means of the ADDROUT 
option of the independent OS/3 sort/merge program; this process is documented in the 
sort/merge user guide, UP-8342 (current version). 


For details of the actual programming specifications you must use for creating and 
processing IRAM files in OS/3 using RPG Il, refer to the RPG II programmer reference, 
UP-8044 (current version). 


*The IBM System/3 programmer recognizes the file created to be processed with all volumes mounted as an online 
multivolume tile; the file created for single-volume processing he recognizes as an offline multivolume file. 
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13.1.1. Processing Sequential IRAM Files 


A sequential file is one organized consecutively, its records being written on the disk in 
the physical order in which you provide them to IRAM. They are usually processed 
consecutively, one after the other, in the order in which they occur on the disk, and 
usually all the records in the file are processed. IRAM furnishes you functions for 
consecutive processing, but also provides functions for random processing, by relative 
record number. The following subsections discuss procedures for creating and extending a 
sequential IRAM file; for adding, retrieving, updating, and deleting records; and for 
reorganizing a sequential IRAM file. 


13.1.1.1. Creating a Sequential IRAM File 


You define your IRAM file as an output file to be created in a sequential (consecutive) file 
processing mode, and you specify the uniform size of your fixed-length records and the 
size of your data buffer (or buffers). You may use two contiguous |/O areas, each half- 
word aligned, for double buffering if you desire, but they must have the same length. 


To calculate the minimum size that you may specify as data buffer length, use the 
following algorithm: 


ze if record size divides into noe bytes without remainder, minimum buffer size is 256 
bytes. 


= §= If record size is a multiple of 256 bytes, the minimum buffer size equals record size. 


# Otherwise, minimum buffer size depends on the sum of record size + 255 bytes. If 
the sum is a multiple of 256 bytes, then the minimum buffer size equals this sum. If 
not, you must round this sum upward to the next multiple of 256 bytes; this, then, is 
the minimum buffer size. 


The same algorithm is used for minimum data buffer length calculations in creating direct 
and indexed IRAM files as well. To specify data buffers larger than the minimum may 
enhance your program's performance. Note that subsequent programs processing this file 
need not specify the same data buffer size that you use to create the file, but they must, of 
course, specify at least the minimum. 


After the file is opened, your records are submitted to IRAM, one after the other, until you 
have no more records available. IRAM stores them in the data partition in the order of 
submission — this is the consecutive order in which you may process them later. The 
relative record number of the last record written is recorded by IRAM in the file control 
table and the volume table of contents. Records are stored as a single, compact string of 
bytes, without any space in the string unused or devoted to system overhead. IRAM 
performs no sequence checking or duplicate record rejection in loading a sequential IRAM 
file; these functions, if they are necessary, are up to your programs. 
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13.1.1.2. Extending a Sequential IRAM File 


Once the string of data records has been created, it may be enlarged through IRAM only 
by appending new records at the end. IRAM does not provide functions for inserting new 
records within the string, nor for adding them at the head of the Sting: Records may not 
be appended during retrieval processing. 


The usual method of appending new records to a sequential file is essentially the same as 
file creation. Again, the file is defined as an output file for sequential processing, and the 
same specifications made as before (except, as previously noted, that this program need 
not use data buffers of the same size as the file-creating program used). After the file is 
opened, your new records are submitted to IRAM and stored in consecutive order, as in 
file creation; all are appended to the data string. This procedure requires you to specify the 
EXTEND option in the LFD job control statement for the file. 


It is also possible, in IRAM, to extiand: a sequential file in random mode — again by 
appending each new record to the end of the string. For this manner of enlarging the file, 
you redefine it as a chained output file for random (direct) processing, and you define a 
field in your program to be used for providing a.relative record number for each new 
record IRAM is to append. You must also define a record work area in your program (equal 
in size to one record length) in which you make each record available to IRAM. When the 
file is opened, IRAM automatically initializes the relative record number field to the next 
record number available for file extension. You use this for the first record to be appended, 
incrementing the field by 1 for each succeeding record before you issue the output 
MOEHON to append it to the file. 


13.1.1.3. Adding Records to a Sequential File 


When you have to enlarge a sequential file by inserting new rebords paeieen existing 
records, or by adding them at the head of the string, you must make use of processors 
other than IRAM, which has no sequential or random functions for performing these tasks. 
Your new records must be sorted into the consecutive sequence in which you expect to 
process them, and be provided as an input file (together with your IRAM file). to either the 
OS/3 independent sort/merge program or the OS/3 data utilities program. Either. of these 
processors can be used to create a new sequential IRAM file containing your inserted or 
added records in their proper consecutive order. Refer to current versions of the OS/3 
sort/merge user guide, UP-8342, or the OS/3 data utilities user guide/programmer 
reference, UP-8069, for the details of these procedures. 


13.1.1.4. Retrieving and Updating Records in a Sequential IRAM File 


You may retrieve or retrieve-and-update records in an IRAM file either in sequential 
(consecutive) order or at random (using relative record number). Recall that if yours is a 
multivolume file, however, it must have been created for processing with all volumes 
mounted if you are to process it via relative record number (see 13.1). For consecutive 
retrieval, define the IRAM file as a nonindexed input file for sequential (consecutive) file 
processing mode. For consecutive retrieval-and-update, define the IRAM file as a 
nonindexed update file for sequential processing. If your processing is to begin elsewhere 
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than at the first record of the file, you must predefine a field in your program where you 
must provide the relative record number of the starting point to IRAM by setting a lower 
limit for processing before you issue: the input function (these actions are not required 
when your program is to read all the records). Your retrieval may begin at any record 
number that is not higher than the current file limit; once this record has been retrieved, 
however, the remainder of the records in the file are read automatically in unbroken, 
consecutive order, unless you select a second starting point. 


vou may ious two data buffers if you are only retrieving records without updating, but 
you must provide only one data buffer if you are updating. The lengths of these buffers 
must be the same, but need not: equal the data buffer size used to create the file. 


IRAM provides data records to you in the data buffer in the same consecutive order in 
which it received them at file creation or extension, and in the same order that they were 
written on the disk. Consecutive retrieval continues until the file is closed or the end of file 
is reached; if it is to be terminated by the end-of-file condition, you must have specified 
the address of a routine for handling this event: If the relative record number you specified 
as the starting point lies outside the file limit, retrieval does not take place; control is 
transferred to an error routine with status flags set to indicate a no-find condition. 


Random retrieval by relative “esord number from a sequential file requires ‘hae you define 
the file.as a chained input file for random processing by relative record number. Your 
program defines a field in which you will supply the desired relative record number to 
IRAM and moves this number into the field before you issue. the input function. If you 
request a number that lies outside the current file limit, IRAM transfers control to an error 
routine with status flags set to indicate a no-find condition. Random retrieval terminates 
when the file is closed. 


For random retrieval-with-update from a sequential file, you proceed as for random 
retrieval, but.you may predefine a field in your program as a record work area (of a size 
equal to record length) from which you will make the updated record available to IRAM 
instead of using the data buffer. (Only one data buffer may be used in the update mode.) 
IRAM will make the retrieval record available to you in this record work area, instead of in 
the data buffer, if your program specifies if before you issue the input function. You 
retrieve by supplying IRAM with the desired relative record number in the predefined field 
of your program before you issue the input function. The output function to write the 
changed record back to the file does not require a relative pacore number and none should 
be supplied. 


Updating records in any IRAM file may include marking records that have become inactive 
with a deletion flag — according to your own conventions. Such records will always be 
retrieved; therefore, if your update processing does include the writing of a deletion flag, 
then your retrieval programs must include checking for the presence of this flag to 
Retetnine whether mast record retrieved is to be bypassed or processed. 


Records may not be appended during retrieval or retrieval-and-update operations. — 


roa 
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Lad i iy es Deleting Records from a Seduentiel IRAM File 


IRAM does not provide a function for logically deleting eoords from a file: nor. for 
physically removing them from the unbroken string of data records. As records become 
inactive or otherwise eligible for removal from the file, your update programs should mark 
them in some way (of your own choosing). so that they can be recognized for bypassing — 
and for eventual physical removal when you reorganize the file. A common method for 
logically deleting a record is to write a conventional deletion flag ina specific byte of the 
record. Because IRAM has no means of checking this flag for you, logically deleted records’ 
will always be retrieved; your programs must check for the presence of the delete code. 


13.1.1.6. Reorganizing a Sequential IRAM File. | 


A sequential file may eventually require reorganization. One reason may be to conserve 
disk space by physically removing records that have been logically deleted from the file; 
another may be to reorder the file according to a more convenient physical sequence than 
was used to create or extend it. 


Two methods are available to you for reorganizing a sequential file. Either the independent 
sort/merge program or the data utilities program will accept your IRAM file as input and 
resequence the data records, physically deleting records you. have tagged. For details on 
these processors, refer to the current versions of the sort/merge user guide, UP-8342, 
and the data utilities user guide/programmer reference, UP-8069. i 


13.1.2. Processing Direct IRAM Files _ 


A direct IRAM file is one organized to allow any record in ‘the file to be retrieved directly 
when the location of the record, in relation to the beginning of the file, is specified. The 
IRAM processor does not search an index or process other records that precede the one to 
be retrieved; all records in the file are assigned to. specific file-relative positions, 
independent of the order in which they are presented to IRAM for writing to the file. 


IRAM provides not only functions for direct or random processing but also functions for 


consecutive processing of records in a direct file. The following subsections diskuss 
procedures for creating and extending a direct IRAM file; for adding, retrieving, updating, 
and deleting records; and for reorganizing the file. 


13.1.2.1. Creating a Direct IRAM File 


When your plans for processing a nonindexed IRAM file call for each record to be assigned 
to a specific disk location, you create a direct file by presenting your records, one by one, — 
to the IRAM processor in a work area, and by supplying the file-relative position to which 
each record is to be written on disk. This position. is not a disk address, but a file-relative 
record number that you supply to IRAM Ina predefined field of your program before. your 
issue each output function to write a new record to disk. The RPG II programmer knows _ 
this type of file as a chained output file. 
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The relative record number that you assign to each record as it is written out may have 
been determined directly from some control field in the new record itself, or it may have 
been derived from the record by a conversion. process that you have programmed 
separately. Or, it may have been obtained from some other source entirely: a control field 
ina record in some other file. In any event, it is entirely possible that a number of the 
relative record positions available in the extent you have allocated to this direct IRAM file 
will not be occupied by a data record in your initial load. It is also possible, on the other 
hand, that your method of obtaining a relative record number may result in your assigning 
the same number to two or more records.. 


When you are creating a direct IRAM file randomly by relative record number, IRAM does 
not check for duplicate assignment of relative record numbers, nor does it detect or 
prevent two records being loaded into the same position in the file. Later addition of 
records or extension of the file may, likewise, result in overwriting record positions already 
containing valid records that you do not intend to be “‘updated” in this backhand way. 
Such problems must be dealt with in your programming and in your preparation of the file 
before you load. 


IRAM preformats the extents of direct files residing on the variable-sector 8411, 8414, 
8424, 8425, 8430, and 8433 disk subsystems, initializing or “dummying” all relative 
record positions to binary O; it does not do so, however, for files on the fixed-sector 8415, 
8416, and 8418 disks. Record positions on the latter disks will contain spurious data (from 
your point of view) resulting from previous uses of the disk, or residual patterns from prior 
disk prep or testing routines. Before loading a direct IRAM file onto an 8415, 8416, or 
8418 fixed-sector disk, you should therefore take care of dummying with a file preparation 
program of your own: one that writes into all record positions the null pattern (blanks, 
zeros, or whatever you determine) that your subsequent load program will recognize as 
virgin territory. In this way, the algorithm in your load program for detecting and 
preventing the collision of synonyms will be more likely to work as you intend. 


In calculating the minimum size of your data buffers, follow the same ep procedake as for a 
sequential file, described in 13.1.1.1. 


13.1.2.2. Extending a Direct IRAM File 


You enlarge or extend a direct IRAM file, which has been created randomly by relative 
record number, in the same way as you created it. That is, provide each new record to 
IRAM, singly in a work area or I/O area, and supply the relative record number for the 
record before you issue the output function to write it, placing this number in a predefined 
field in your program. 


When a direct IRAM file is opened for extension in random mode, IRAM automatically 
initializes the predefined relative record number field in your program by moving into it the 
next available record number. This number is the next relative record position where IRAM 
expects to write the first data record to be appended to the string of records in the file. It 
has recorded this record position in the volume table of contents (VTOC) of the file and in 
the file control table as an end-of-data address. 


a 
-_ 
? 
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You must use this IRAM-supplied relative record. number with the first new record you add 
to the file, and each successive relative record number you provide (by incrementing the 
content of this field) must be. 1 higher than the current highest numbered record. 
Therefore, if you are enlarging your file by adding data records by relative record numbers 
that you are calculating or obtaining by algorithm, your file extension program should 
provide a dummy record for each consecutive relative record position to which a record 
containing actual data is not to be written. (An alternative, of course, is to.extend your: 
direct file with all dummied records, to.be updated later at random by. actual data records 
whose relative record numbers you provide by the same process used in file creation.) In 
either case, the dummying is your own convention, pe ec by your Bicgremss — not by 
IRAM. . 


Records may not be appended during retrieval operations. 


13.1.2.3. Adding Records to a Direct IRAM File 


In the sense of appending new records to the end of the string of data records in.a direct 
IRAM file, adding records extends the file; this process is described in the preceding 
paragraph. In the quite different sense of inserting. new data records into the existing data 
string, however, adding new records by relative record number is tantamount to updating 
without prior retrieval. However, an important difference between this way of adding 
records and the update procedures described in the following paragraph is that your direct 
file must not be defined as an update file. 


To insert new records by relative record number without first retrieving the record at the 
specified file-relative position, you must deine your. file as an output file. To add a new 
data record to an output file in this method, your program must predefine both a record 
work area (size equal to record length) and the field in which you supply to IRAM the 
relative record number of the position. within the file to which the new. record is to be 
written. You Set the relative record number in this field before you issue ne output 
function. 


Whether you use this. method. of inserting. new data records into a direct IRAM file 
depends upon your methods for generating or obtaining relative record numbers and for 
dealing with synonyms. Some methods rely on your examining a record position before 
you add a new record; to add bindly in these methods would eventually destroy the 
integrity of your file. 


13.1.2.4. Retrieving and Updating Records in a Direct IRAM File 


There are three methods available for record retrieval or retrieval-with-update from a 
direct IRAM file. If you specify sequential processing mode, you may retrieve data records 
in the order in which they occur on disk. You may retrieve records randomly by supplying 
relative record. numbers in your program, and you may retrieve records randomly by 
processing: your direct IRAM file with a tag file that contains a set of relative record 
numbers produced by the ADDROUT option of the sort/merge program. 
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For consecutive retrieval, define the direct IRAM file as an input file for sequential 
processing mode; for retrieval-with-update, define it as an update file. (Only one data 
buffer may be specified for update mode.) When you issue the input function, consecutive 
retrieval pagins automatically with the first record position in the data belnen 


if you do not want to begin processing with the first consecutive record in the file; you 
may issue the appropriate function to set a different lower limit for retrieval. You must do 
this after the file is open, having predefined a field in which you provide the relative record 


number of the starting position desired for retrieval. Your first input function retrieves the 


record at this position, and the succeeding input functions retrieve data records: in 
consecutive order. You may reset the lower limit at any time while the file is open. 


To retrieve randomly by relative record number, define the direct IRAM file as an input file. 


for random processing mode; for retrieval-with-update, define it as an update file. Your 
program must predefine the field in which you supply IRAM with the desired relative 
record number, which you do before issuing each input function. The output function for 


writing a retrieved, updated record back to its original disk location does not can a 


relative : pecorek number, ane none Shou be supplied. 


If your “updating programs include ‘provisions for tagging - records for deletion, or 
overwriting them with a null pattern (blanks, zeros, etc.) So that they may be recognized as* 
available. for reuse, your retrieval programs should include a check for these conventions. 


in order to avoid unnecessary processing of invalid records. IRAM itself has no means of 
avoiding the retrieval of logically deleted records. . 


If your file contains synonyms, your ‘retrieval and_ updating programs must, obviously, 
contain the necessary coding: to locate the desired recone: - 
13. 1.2.5. Deleting Records from a Direct IRAM. File 


Becuiise IRAM does not provide a funicion for jouically selenng a record an a file, your 
update programs should provide for whatever means are necessary, according to your own 


conventions. Although you may flag each record for later deletion when your updating > 


program determines that jit-is eligible for. removal from the file, consider also the 
alternative of overwriting a record that:you no longer want to process with the null pattern 
that (according to your own programming conventions) is recognized as ‘a relative record 
position available for reassignment to a new record. Depending upon your. method of 
handling synonyms in your direct file, there may be synonym linking or chaining 
information in a record that should not be deleted when its data content is inactivated by 
your logical deletion procedure. 


13. 1. 2. i Reorganizing a Direct IRAM File 


Unlike ‘a sequential IRAM file, a direct file cannot be. usefully rearcaneed: with’ the 


sort/merge or data utility programs. It is not feasible, for example, to physically remove 
records flagged for deletion in copying a direct file with the-data utility because of the 
inevitable change in the file-relative positions of the valid records carried over to the new 
file. They are carried over in the same consecutive order that they held in the old file; but, 
because the data utility has no means of generating new relative record numbers and 
substituting these in your synonym linkage fields, these fields are unchanged and are no 
longer valid. 


os 
< F ; 
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Even though your file does not contain synonyms, if the valid records are to be written to 
relative record positions. contained in or: derived from a control field in-each record, the 
data utility or sort/merge program nonetheless lacks the facility to write them to the 
desired locations in the new file. A method for compressing a direct file without synonyms 
would be to copy it consecutively, via the data utility, and to use the resulting sequential 
IRAM file as input to a direct IRAM file-creation program you have written in RPG Hl. This 
effectively recreates a direct IRAM file in a smaller disk space. 


For details on the use of the data utility, ee to the data utilities user guide “programme 
reference, UP-8069 une version): . ms 25 


13.2. PROCESSING INDEXED IRAM FILES 


Indexed IRAM files contain two separate partitions: a data partition with fixed-length 
records ordered consecutively in the order of submission and stored (exactly as in 
nonindexed IRAM files) in a single compact string of bytes; and, an index partition, 
containing blocked index entries at two or more hierarchic levels. Each data record in the 
data partition contains a key, a character string specified by.the user, that. uniquely 
identifies the record. All keys in the IRAM file are of the same length; a key may start at 
the head of the record it identifies, or it may be elsewhere within the record, but the 


‘location of all keys must be the same for all records in one file. For details on the StrueTUre 


of RSyou records and the ne index, refer to 1222. 


If aha. index partition is activated’ ‘duane processing, data records may be referenced 
randomly or sequentially by the values of their keys. When the index partition is inactive, 
data records may be accessed.consecutively (in the physical order ‘in which they occur on- 
disk) or randomly, according to their relative positions in the data partition. However, 
records may not be added unless the index is active. ere the index is a Specie 
detail: of file definition, me before. the file is ope nee a 


A ranitvoluiae indexed IRAM file may be eiéated for processing with all volumes sales ‘or 
with only one volume online at a time, and it must always be processed in the mode for 
which it was created. When a multivolume file is created for single-volume processing, 
random processing must always use the keyed retrieval functions, for which the index 
pavutien must be active; random retrieval by record number is. not pe 


Both multivolume and ainele volume indexed: IRAM files may be created in an ee or 
disorderly load. In an ordered load, records are submitted to IRAM in ascending order of 
key: values; an out-of-sequence record is rejected, and an error is reported. In an 
unordered load, no checking of key sequence is performed by IRAM.: In both types of load, 
however, IRAM checks for duplicate keys; a record whose key copienes a key already in 
the file is rejected, and an error is reported. 


A new data record with a key duplicating one already in the file may not be added to the 
file at any time. No sequence checking of keys may be specified during file extension 
operations. All IRAM files may be processed randomly with a-tag file containing relative 
record numbers of the records selected for processing. Such a disk file may be prepared 


from the IRAM file by using the ADDROUT option of the independent sort/merge program;. 


for details, see the sort/merge user guide, UP-8342 (current version). In addition, an 
indexed IRAM file may be processed sequentially with a file containing record key limits. 
Alternatively, the lower limit may be set within the RPG Il program. 
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The following subsections discuss, in general terms, procedures for creating and extending 
an indexed IRAM file; for adding,. retrieving, updating, and deleting records; and for 
reorganizing an indexed IRAM file. For detailed programming specitications, refer to the 
RPG Il Programmet reference, UP-8044 (current version). 


13.2.1. Creating an Indexed IRAM File 


You define your IRAM file as an indexed output file and present each data record to IRAM 
in a predefined record work area (of a size equal to one record length) before you issue the 
output function to write it to the data partition. All data records are of a uniform length, 
and each contains a unique record key. You must specify the record length, the key length, 
and the fixed location of the key in all records when you define the file. 


Other specifications you must make in defining the file include: 

# the re re dereee of your deeceiodae buffer: 

a ‘ioe and addressee vol des biter siti | 

# the address of a field in vault program that is to contain a search key. 


For calculating the minimum data buffer size you may. specify, follow the same procedure 
used for creating a sequential IRAM file — described in 13.1.1.1. The primary data buffer 
is half-word aligned and contiguous to the index buffer in main storage. You may 
optionally specify a secondary data buffer (except. for update operations); this must be 
contiguous to the primary buffer and of exactly the same size. The pecondany data buffer 
follows the primary buffer in main storage. 


The index buffer in main storage is also half-word aligned and. has a minimum ede of 
256 bytes; if larger, its size must be a multiple of 256 bytes. The RPG II compiler specifies 
this minimum length for you and provides you with means for increasing the size of the 
index buffer (by one -or more (up to nine) 256-byte increments) to enhance the 
performance of your programs: not only the load program itself, but all programs 
subsequently accessing the indexed IRAM file when its index is active. You should do so if 
you can afford the main storage, bearing in mind that all subSequent programs that use 
keyed functions must specify the same index buffer size you used to create the file. eUBHeY 
need not use the same data buffer size, however; see 13.1.1.1.) 


A good ‘ille of (hun: in. sererniining your .index buffer size is to multiply the sum of your 
specified key length plus three bytes by 20, rounding the result upward. to the next 
multiple of 256 bytes. This figure is used in eee disk SBEee required: for an indexed 
IRAM file (see 12.2.4). 


The length of the field you must predefine in your file creation program to hold a search 
key is your specified key length plus three bytes. This field is required in any program that 
uses keyed functions. IRAM uses this field itself, and sometimes overlays it. Your 


programs should avoid this field except for Piscine a search key in it, ve prior to 


peQueSeg a ranger read. 
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In defining the file for creation, you may specify that IRAM is to check that the sequence 
of the keys in your submitted data records is in ascending order. If you do so, you must 
submit them in this order for the load (but not necessarily in subsequent file extensions); 
an attempt to load a data record containing an out- of-sequence or duplicate key is rejected | 
immediately, and an error is epee 


If you do not request key sequence checking, you may submit your data records to IRAM in 
any key order; only duplicate keys will be rejected. Depending on the bias of your key 
distribution in this disordered load, you should expect the process to be less than half as 
fast as an orderly load with sequence checking. : 


13.2.2. Extending an Indexed IRAM File 


Once the file is created, it may be extended in ‘the. same manner we have just dsaefipad 
for creating the file. IRAM appends new records to the end of the data string. If you have 
specified sequence checking in creating the file,.you are not constrained to extending the 
file with an orderly sequence of added record keys, but if you do specify sequence 
checking for extending the file, the key in each record submitted.must be successively 
higher than any in the file or volume. Duplicate keys are rejected. You may also add new 
records while you are retrieving existing records from the file; see. 13.2.4. 


Once you have successfully added a new record to an indexed IRAM file, it is immediately 
available for retrieval. This is true because IRAM updates the index structure on a record- 
by-record basis during load, extend, and add operations. It does not sort the index 
following a disorderly load, but maintains the fine-level index in unbroken ascending key 
order at all times. Refer to 12.2 for details. 


13.2.3. Retrieving and Updating in an IRAM File with Index Active 


When a multivolume indexed file has been created for single-volume processing, random > 
retrieval from each volume must always be performed with the index marked active, using 
the key of the desired record as a search argument. It is not possible to retrieve records 
from the mounted volume at random by relative record number. | 


Random retrieval from a single-volume indexed file is not limited in this way. You may 
retrieve records at random by key when the index is active, and at random by relative - 
record number when it is not. The same is true for multivolume files created for 
multivolume processing. When the index is marked inactive, IRAM files may be processed 
only in retrieval and update modes, as described in 13.2.5. When the index is marked 
active, all retrieval from an IRAM file is done by key. 


To retrieve randomly by key, define the file as an input file for random mode processing 
and specify that the index is active. Your program predefines a field in which you provide 
IRAM with the key of the desired record as a search argument before you issue the input 
function. The length of this field is three bytes greater than the key length specified for the 
file. No search key may contain a byte with the hexadecimal value ‘FF’. 
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If you have specified update mode, random retrieval may be followed by an output function 
to update the record retrieved: IRAM prevents you from issuing the update function if the 
desired record has not been found. In updating ‘a keyed record, you should take care not to 
alter its key in any: way. IRAM.does not check for alteration of the key nor does it prevent 
your update from being issued if the key of the updated record duplicates one already in 
the file. IRAM updates without reference to the index; therefore, if an updated record is 
written back to the file with a key that has been nenenged subsequent retrieval by key is 
Sey impossible ‘or unreliable. : 


Se cental retrieval by key requires that the file be defined as an apet file for sequential 
processing and that the index be marked active. Before you issue the input function to 
retrieve the first record, you must establish the value of the record key at which the 
retrieval sequence is to begin. This is done by issuing a function to set the lower limit for 
retrieval and providing a key value in a predefined field of your program. IRAM will then 
search for a record containing a key equal to or greater than this value. 


If the value you supply is zero, the record retrieved by your first input function is the - 
record containing the lowest key in the file. (This is the first record in the data partition © 
only if the file was created with an orderly load.) If the value you Supply is greater than the 
highest key contained in the fine index, no retrieval seauence can Bean In es case, © 
IRAM reports a “‘no-find”. 


Once a sequential by- “key retrieval Sequence has been successfully ‘started, it continues 
A oo 


# - you reach end of file ‘Gr end of salts - . | ate Be e 
™ you specify a new lower limit to start a _— Seateatial retrieval sequence; 
= you reset file processing mode from sequential to random; or — 

a the file is closed (by your program or by IRAM, as in case of I/O error). 


A sequential- by- key retrieval sequence is not terminated when you add a new record 
during retrieval operations, but is resumed with your next input function (see 13.2.4). 


If your updating operations include provisions for flagging records (by your own 

conventions) that are to be deleted from the file, your retrieval programs should include: 
coding to check for the presence of this delete flag, and to bypass or process each record © 
accordingly. IRAM does not recognize your deletion code and will not avoid retrieval ‘of a 

flagged record. 


13.2.4. Adding Records during Retrieval — Index Active 


Provided that you have marked the index active and have specified that you intend to add 
during retrieval, you may provide a new record to IRAM in a predefined work area in your 
program and request that it be appended to the file. IRAM refuses the action if the key of 
the new record duplicates a key already in the file, but the value of the key may be lower cc 
than or greater than any key in the file, or fall within the range of the existing keys. You Mag 
may not specify that IRAM is to check key sequence when you add during retrieval. 


‘ 
i 


Serre, 
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If you append a new record in this manner during a sequential.retrieve-by-key operation, 
the retrieval sequence is not terminated, but resume with your next issue of an input 
function. A record may not be added to an indexed IRAM file unless its index is active. 


13.2.5. Retrieval and Update when Index Is Inactive 


An indexed IRAM file may be Sispeeead only in aetisval or satieval: and- update modes 
when the index is marked inactive. Update is not possible-without prior retrieval. Programs — 
accessing such files may not issue. any keyed function, nor may they add new records. 
Attempts to extend the data partition are disallowed and result in an error report with 
status flags set to indicate an invalid macro issue. IRAM does not use an index buffer for | 
the nonkeyed retrieval or update functions allowed for an indexed IRAM file processed 
with an. inactive index, and therefore, your Brogtarm does not require or gerne an ness 
buffer. ; 


When its index is inactive, random retrieval and retrieval-with-update of an indexed IRAM - 
file may be performed by relative record number — but only if the file is a 1-volume file or 
was created for multivolume processing and all volumes are mounted. Define the file as 
an input file for random processing mode, with update if desired. The file may not be 
defined as an output file. Your program predefines the field where you provide the relative 
record number of the desired record before you issue the input function to retrieve it. An 
input request with a file-relative record number higher. than. the highest number recorded 
for the file results in transfer of control to your error routine, with status flags set to 
indicate an end-of-file condition. To.terminate random retrieval, you close the file. For 
update, you may use a work: area (length equal to one record length), or one data buffer to 
present the updated record to IRAM..Two buffers. may not be epeciuce for update 

processing. ~~ . | 


The other method for retrieval or retrieval-with-update, from an indexed IRAM file with its. 
index inactive, is consecutive processing. For this,:- define the file as an input file for . 
sequential mode oes ut update if Besired) and mark the index inactive: 


If yours is a. 1 sevice file, or was eeanied foi multivolume processing and all volumes: are 

to be mounted, you may set the lower file limit for consecutive retrieval. Your program . 
predefines a 4-byte field in which you supply IRAM with the file-relative record number 
where consecutive processing is to begin; you move this number into the field before you 
issue the function to set the lower processing limit. Your first input function then retrieves 
the record at this file-relative address, and your successive input functions retrieve the 
remaining records in their consecutive, physical order on: disk. If you do not set a lower — 
limit, consecutive retrieval starts with the first record in the file. Retrieval terminates when 
IRAM detects end-of-file; it detects end-of-volume conditions automatically and issues: . 
mount messages to the operator for subsequent volumes. 


If your file is a multivolume indexed file created for single-volume processing, you do not 
have the option of setting a fi/e-relative lower limit for consecutive retrieval. If you are to 
provide a record number to IRAM intended to be a lower limit for retrieval, you must 
realize that IRAM treats this as a vo/ume-relative record number — the first record in the 
volume data partition being record number 1. (This is the first record retrieved if you do 
not set a lower limit.) Consecutive retrieval terminates when end-of-volume is detected by 
IRAM. 
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13.2. e Deleting. Records from an Indexed IRAM File 


Séeaucs: IRAM does not. provide a fdaction: for deleting, records from your files, you must 
tend (yourself) to whatever is necessary for this purpose in your programming. A common 
method of logically deleting a record from a file that is being updated is to mark it with a 
deletion code: for example, a specific character in a specific data byte. Records so marked 
or flagged for deletion may later be physically removed from the file when it is reorganized 
— offline from IRAM processing. In the meantime, your retrieval programs should be 
coded so as to check for the presence of your conventional deletion flag in each record 
retrieved so that a logically deleted record may be recognized and bypassed. IRAM has no 
provisions for recognizing your Benen flag and are the retrieval of records 
containing it. 


In establishing your own convention for logical deletion, restrict your flagging to one or 
more data bytes, recalling the unpredictable results of changing the key of a record in.an 
indexed IRAM file during update (12.2.3). The index of the IRAM file is not available to you 
for marking index entries that refer: to records you intend to be logically deleted, and you 
should not attempt this. . eS 


13: 229: peaseniZins an Indexed IRAM File 


You may have occasion to reorganize an indexed IRAM file: for avanapie: to compress it by 
physically removing data records tagged for deletion, or to resequence the data records for 
more efficient or convenient processing. If you have created or extended your file with the 
disorderly load option, but then find increasing need to scan it in key sequence, you would 
improve your sequential retrieval program’s performance as a result of dumping the file 
and reloading it in an ascending key order. 


To reorganize an IRAM file, you will generally need to use other processors: either the 
independent-sort/merge program, or the data utility program. Either. of these, for example, 
will accept. your IRAM file as input and delete or omit records as specified in the process. 
of sorting or copying and recreating the file. These procedures are documented in the 
current version of. the sort/merge user guide, UP-8342. and the data eS user 
Suige/“Aiouraliiner reference, UP-8069. te EF 


When your multivolume indexed IRAM file has been created for single-volume processing, 
you: may find a need to regroup data records onto different volumes for more convenient 
processing. You cannot perform this task with the data utility program, however, because 
the utility is not parameterized to allow you to select the volume onto which a given record — 
is to be copied. For this. sort: of Feorganization, therefore, you would nBeG to prepare a 
specific RPG II program. . 
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13.3. DEFINING AN OS/3 IRAM FILE (DTFIR) 


The DTFIR declarative macro is used to define an IRAM file to data management. It 
establishes a 240-byte nonindexed file table or a 307+KEYSIZE-byte indexed file table. 


Normally, you do not need to know what the format of the DTFIR macro is because the file 
definition statements you use in your program to define the file are effectively translated 
into a DTFIR macro. 


If, however, you want to temporarily change your file definition at run time by using a DD 
job control statement, you must know what the format is. To help you in these cases, the 
DTFIR Macro format and a summary of the keyword parameters (Table 13—1) that 
indicates which parameters can be changed by the DD job control statement are provided. 
Examples of typical DTFIR macros follow Table 13—1 and detailed descriptions of the 
individual DTFIR keyword parameters are provided in 13.4. 


Format: 
LABEL A OPERATION A | OPERAND 
filename ACCESS= ( EXC 
EXCR 
SRD 
SRDO 
[| ADD=YES] 
,BFSZ=n 


[,EOFA=symbol] | 
[,ERRO=symbol] | 
[,INDA=symbol] 
[ INDS=n] 
[, INDX=YES] 
1O0A1=symbol 
[ 1|OA2=symbol] 
[ |ORG=(r)] 
[,K ARG=symbol] 
[,KLEN=n] 
[,KLOC=n] 


[LOCK=NO] 





Y + 
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A OPERATION A : OPERAND 


filename DTFIR (cont) /MODE= a 
| | enn 


‘LOPTN=YES] 
,RCSZ=n 
[, SKAD=symbol] 


[ SOCK=YES] 


Rive = 


[,UPDT=YES] 





[, VRFY=YES] 


_LMMNT=ONE] 





[,WORK=YES] 





Table 13—1. Summary of DTFIR Keyword Parameters (Part 1 of 2) 


Keyed Operations | Nonkeyed | Nonkeyed Operations | 
Keyword Specification Restrictions Remarks 
INPUT | OUTPUT | INPUT OUTPUT 


ACCESS* EXC This DTF: read/update/add use 
Other jobs: no access 


















EXCR ; This DTF: read/update/add use 
Other jobs: read use 
SRD This DTF: read use 
; Other jobs: read/update/add use 
— ae 
haat = eee = 
















This DTF: read use 
Other jobs: read use 

















Indicates new records are to be added 
to a file 


‘Always required Supplies data buffer size 


Required if MODE=SEQ Address of end-of-file routine 
ie eee eel Address of error-handling routine 


Used only with keyed operations Address of main storage area to 
contain index 


. Used onty with keyed operations 


BFSZ* 


EOFA symbol 


INDA symbol ee 


INDS** 
INDX 


1OA1 symbol 
1OA2 symbol 


Used only with keyed operations Indicates size of index area 
Used only with keyed operations Indicates keyed operations 


Always required Address of primary buffer 
Not permitted when UPDT=YES Address of secondary buffer 
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Table 13—1. Summary of DTFIR Keyword Parameters (Part 2 of 2) 


Keyed Operations | Nonkeyed Operations 7 
Keyword Specification. ; ieee ee Remarks 
~. PO ENPUT | OUTPUT | INPUT OUTPUT ey ts 
IORG (r)=general register fo | x [| o| Not permitted when WORK=YES Indicates 1/O buffer index register 
x x Used only with keyed operations Address of field containing key of 
eA desired record * : : 
nae Be xX Used only with keyed operations Indicates key length 
KLOC** n x xX 
of the key within a record 













Restrictions 





Used only with keyed operations Indicates the byte number location 






Optional file for sequentially 
processed files. 
| oR Required if MODE=RAND Address of seek address field 
YES x x x Used only with keyed operations Indicates that sequence of keys for 
ordered load should be verified 





: Indicates output file type 
x Input only ~ 















YES x Indicates update capability 
4 : Used for TYPE=INPUT and Read/check of output records 
antl By & be 











permitted only when ADD=YES | to be performed 


or UPDT?YES 





Not permitted when MODE=RAND) 
unless INDX=YES 


Defines file to be processed with — 
only one volume online at any time 











Also required for keyed 
operations when TYPE=INPUT — 
and ADD=YES. Not permitted 
in conjunction with IORG 


Indicates that the record processing 
is in a work area 


Oo 
Zz 
m 


WORK YES 18) 


LEGEND: 

O = Optional 
R = Required 
S = Select one 
X = Not used 


*Parameter may be changed on DD job control statement. 
**Parameter may be changed on DD job control statement for index mode only. 
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Example (IRAM Output File): 
































LABEL Boren Ariane ¥ ya A COMMENTS - 
erie rap FORMAT. FOR CREATING AN INDEXED buTPuT FILLE, LABELED 
He aes po bh a a 
L eb ppl pod NS ee Ee be Dt ee pac ee A FB 
Fie. | tp Kl ig apy AW ha logs ep ag OE Pe En ee ed ge a XK 
pani sa en : 
ERKROAER 7 hus x 
Pees tis tii | AL aiePer, 1 bata 
Pees tu tii, | Eps. 2256 x 
Picigat Pach elt Ie DE ier ack nao le eg Cpa ae ce ea ee ea 
Pali | RAR ZAREAL : deo a XL 
ceed de deh seek | IK LEN=i3,0 | eS ete e nee KI 
pach KLOC.=19, i POSTS ene eee eee ; 
Een So dake ODE. =i A 1 tb Feet OP a Xl 
Peta Li pe vour 2 | | | 


Example (IRAM Input File): 






































LABEL eee ONE OPERAND A COMMENTS 
1 16 ; 72 
Me 2 ORMAT. Fie PRO SING AN INDEED CNPUT, FILE tid : 
ase 2 DoPDLLEIN .1. 1. ia ke, dott ted i tL Pa ae es ae aks i toa ost peo teria teri irtbiiarn ae Jy 
Reereree sae a A Ts tT ry Cae eC eT Ba Sm WT) eC ed Oa a | 
SLA | Ei) JAD D.= Vi ES. [ee eT es ss SEN eT Td EOC YO aes WO ks LC et ed dC Pl 
ee re ee | bd 
i ate SP aotl! Nee gs | Ew AH END Be lee as was Oe oe a 4 
lio. | eeepeee | | Ree E seen teres raees 
| Fp EMBASE ig La eee i Wevevrss seems t|. 
: OAL=AGPOT 1 FER Ser Mee Ws et WP HP ne at BS eS : q 
ee Bee a | be 
pacify] pe eae | EN DAK =e FA ON OO X 
Eereaires Livers Ak.S Al TES Eee TT CONV Vr Ta Se Es Vs Rn ad ne le rv UR OC IK 
pf] ie EN=B0., wee let ail sid anew alee a eek pas 
Pee oe KbhOCHSe, 11 bee bee 
Pees ti tii. | MaDe aRAND isiled i |! | 
rant dis RCSZ.=1512, bot bea ut de tbo ee Po i eh ee a ge | 





13.4. DTFIR KEYWORD PARAMETERS 


13.4.1. Specifying File Accessing Options (ACCESS) 
See 11.4.1 for a detailed explanation of each ACCESS keyword parameter. 


Note that indexed files should not be shared in an environment that permits only one 
writer to a file but any number of readers. If a file is shared, readers may get 
unpredictable results; that is, DM24, DM39 error messages or no-find errors may result 
when attempting to read records that were previously accessible. Consequently, the 
ACCESS=EXCR or ACCESS=SRD specification should not be made for an indexed file in 
either the DTFIR declarative macroinstruction or the DD job control statement. 
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Records added by the writer (ACCESS=EXCR) to a nonindexed file, in a shared 
environment that permits one writer and any number of readers, are not available to the 
reader (ACCESS=SRD). Once the writer closes the job, any added records will be available 


to users who subsequently open the file. 










































gor, 
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13.4.2. Specifying the Addition of Records to. IRAM Input File (ADD) 


The ADD parameter indicates that records may be added to an input file during record 
retrieval. These additions may be made only to indexed files processed by key. 


Keyword Parameter ADD: 


ADD=YES 
If specified, the DTFIR daclakaive macro must also contain the INDX=YES 
keyword parameter. 


13.4.3. Specifying the Buffer Size for IRAM File (BFSZ) 
The BFSZ parameter indicates the size of the data buffer.in the IRAM file. 
Keyword Parameter BFSZ: 


BFSZ=n 
Is always required. n represents the number of bytes in the data buffer. The size 
must be at least 256 bytes as well as a multiple of 256. To calculate minimum 
buffer size, see 13.1.1.1. . 


13.4.4. Specifying the End-of-File Handling Routine (EOFA) 


When data management senses the end of data while processing an IRAM input file 
sequentially by key or consecutively, it looks for the symbolic address of the user’s end-of- 
data routine and transfers control there. 


Keyword Parameter EOFA: 


EOFA=symbol 
Specifies the symbolic address (name) of your aed routine that dpales ine 
end-of-data condition for IRAM input files. This parameter is required if 
MODE=SEO0O is included in the DTFIR declarative macro; however, it is optional 
for Pgneomnly processed put files. 


13.4.5. Specifying Error Routines (ERRO) 


When data management detects any error or exception in processing, it looks for the 
symbolic address of your error-handling routine. 


Keyword Parameter ERRO: 


ERRO=symbol 
Specifies the symbolic address (name) of the user error-handling routine. When 
data management transfers control to the error routine, filenameC contains 
information on the reasons for the error..(See Tables B—1 and B—3.) If ERRO 
parameter is omitted, control returns to your program inline. 
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13.4.6. Naming Main Storage Location for Index Block Processing (INDA) 
During keyed operations, IRAM processes index blocks in a main storage index area. 
Keyword Parameter INDA: 


INDA=symbol 
Specifies the symbolic address of this index block processing area in main 
storage. The specified area must be half-word aligned and its length must be 
specified in the INDS parameter. The location of the index area in main storage 
must immediately precede the primary I/O buffer area (1OA1). This parameter is 
required for all keyed or indexed IRAM file processing. 


13.4.7. Specifying the Index Area Length in Main Storage (INDS) 


When data management processes indexed (keyed) IRAM files, it uses an index area in 
main storage. The length of this area must be defined. 


Soe Parameter INDS: 


INDS= =n 

Indicates the number of bytes used in main storage for tie index area named in 
the INDA parameter. The index area length must be at least 256 bytes and, in 
addition, a multiple of 256 bytes. Both INDS and INDA parameters are required 
specifications for IRAM indexed files. 


13.4.8. Indicating Processing by Key (INDX) 
Data management processes nonindexed and indexed IRAM files. 
Keyword Parameter INDX: 


INDEX=YES : 
Indicates that IRAM file processing is to be performed by key. THis Sacaniater is 
required for input and output indexed IRAM files. In addition, the parameters 
INDA, INDS, KARG, KLEN, and KLOC must be specified if INDX=YES is used. 


13. 4.9. Identifying the Oy Area we 


When data management processes nonindexed or indexed IRAM files, it always uses at 
least one required |/O area. 


Keyword Parameter IOA1: 


~10A1=symbol — 
Specifies the symbolic address of the 1/O processing area. |OA1 must ‘he half- 
word aligned and greater than or equal to 256 bytes, a multiple of 256, and 
consistent with the BFSZ specification. |OA1 must immediately follow the index 
buffer (INDA), if specified, and must immediately precede the secondary |1/O 
buffer (l1OA2), if specified. 
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13.4.10 Identifying an Additional 1/O Area (lOA2) 
An additional 1/O area may be indicated optionally for double buffering. 
Keyword Parameter IOA2: 


lOA2= symbol 
Specifies the symbolic address of secondary |/O area. Similar to 1|OA1, the |OA2 
parameter must be half-word aligned, the same size as the required IOA1 
parameter, and immediately follow the primary I/O buffer. lOA2 may not be 
SHSeIHed if the UPDT=YES apg is eee 


13.4.11. Pointing to Current 1/0 Per 


When you are not referencing records in work areas, you must indicate an |/O buffer 
index register number. 


Keyword Parameter IORG: 


1ORG=(r) . | 
Indicates the sauisier number ieag: to point to the current |/O area. ‘Abaistats 2 
through 12 are available. Either the IORG or WORK parameter may be specified, 
~ but not both. If both parameters are: pencilled the yOu parent Spee ticaton 
is used. S 


13.4.12. Naming a Place for Key Retrieval (KARG) 


When using indexed (keyed) operations, the user must:name and define a location in his 
program where keys are pega for Retrieve! of. IRAM records. 


Keyword Parameter KARG: 


- KARG=symbol . 
Provides the poles address of. the field in the user's program where keys are 
placed. The length of KARG must be equal to the specification in the KLEN 
parameter plus 3. The KARG parameter is required for all keyed operations. 


13:4.13. Ppeetying Key Lengths for IRAM males aaa 


In processing indexed IRAM files, data paahagement must have the length of keys in an 
IRAM file. 


Keyword Parameter KLEN: 


KLEN=n.. .. . 

- Specifies the Gurber of Bice in-a ee for an IRAM indexed file. All keys must be 
the same length; the minimum length is 3. bytes and the maximum, 80 bytes. 
This. pavaen is. beanies es all eevee Speratlons. 
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13.4.14. Specifying Number of Bytes Preceding Keys. (KLOC) 


Often keys do not appear at the beginning of a record; when they do not, the number of 
bytes offset must be indicated. 


Keyword Parameter KLOC: 


KLOC=n 
Indicates the. number a bytes preceding the key of an IRAM record. The key 
location must be the same within all records of the file. If the key. begins in the 
first byte of the record, KLOC=O should be specified. This parameter is required 
for all keyed operations. If the KLOC parameter is omitted, IRAM assumes a 
value of zero; i.e., the keys begin in the first byte of each record. 


13.4.15. Suppressing a File Lock (LOCK) 


For a detailed explanation of the LOCK keyword parameter, see 11.4.11. 


13.4.16. Specifying Retrieval and Load Modes for Indexed ane: Nonindexed IRAM Files 
(MODE) | . 


Data management can process IRAM flees eequentially or eddorly aceeraing to the 
MODE keyword parameter specification. 


Keyword Parameter MODE: 


MODE=SEQ 
' Specifies sequential retrieval operations for an: indexed IRAM file and sequential 
retrieval or sequential load operations for nonindexed IRAM files. Sequential 
mode is assumed if no MODE parameter is specified. 


MODE=RAN 
Specifies random (direct) retrieval operations for an indexed file and random 
retrieval or random load eperatlions for: a nonindexed: file. 


13.4.17. Specifying Optional Files (OPTN) 


Sometimes you will not need to use a file on every program ‘execution. In this case, the 
file is considered optional. Only sequentially processed input or eo IRAM files can | be 
optional files. . 


Keyword Parameter OTPN: 


OPTN=YES 
Specifies that the sequential input or output file defined by the DTFIR macro is 
an optional file. When this parameter is specified for an-input file not allocated to 
-a device by the DVC job control statement; data management transfers control to 
your EOFA routine on the first issue of an input operation. When the OPTN 
parameter is specified for an output file, data management transfers control to 
your program inline and with no error. 


ATR, 
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13.4.18. Specifying Record Length (RCSZ) 
This polaerer is always required and eperlnee the iencih or each record in bytes. 
Keyword paraniGiee RCSZ: | 
RCSZ=n 
13.4.19. Locating Relative Disk Address for Processing: IRAM File by 
Relative Record Numbers (SKAD) 


When data management randomly processes files defined by the Pn macro, yeu must. 
specify the SKAD parameter. 


Keyword Parameter SKAD: 
SKAD=symbol . . . 
Specifies the symbolic address of an area in your program into which you load 
the relative disk address for use in processing nonindexed files by relative record. 
number. The form of a record address is a 4- byte value, and the first record is” 
relative record 1. " 


13.4.20. Verifying Ascending Record Key Order during File Creation (SQCK) 


Data management can verify that record keys are in ascending sequence during file 
creation. This check is possible only on keyed operations, i.e., indexed files. 


Keyword Parameter SQCK: 
SOCK=YES i‘ 
Specifies that data management should iGhiy ascending key sequence on file 
creation for indexed files. 
13.4.21. Specifying the File Type (TYPE) 


The DTFIR declarative macro describes input and output files. The TYPE parameter 
designates input or output file types. 


Keyword Parameter TYPE: 


TY PE=INPUT 
Specifies a read-only DTFIR file. 


lf omitted, data management assumes the TYPE=INPUT specification. You may not 
issue an output function to this file unless: 


= you specify either the UPDT=YES or ADD=YES parameter; or 


5 you Close the file, reset the file processing direction, and reopen the file. 
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TYPE=OUTPUT | a ee ( 
especies a WEIL ony file. 


You may not issue an aget function to we file unless you Geer: reset, and 
reopen the file. 


13.4.22. Updating Records (UPDT) 

When you wish to update a nonindexed or indexed input file and you have also specified 
TYPE=INPUT, you specify the UPDT parameter. If this parameter is omitted, you cannot 
update a file. 

Keyword Parameter UPDT: 


UPDT=YES 


13.4. 23. ven er Records (VRFY) 


Data management can check parity of output records after they Have been written to disk. 

lf it detects bad parity, data management sets the parity check flag (byte 2, bit 2) in 

filenameC and transfers control to your error routine or to your program inline if you have 

no error routine. Specifying this parameter results in an increase in execution times for 
update and file addition operations. 


Keyword Parameter. VRFY: 


VRFY= YES 


13.4.24. Specifying File Processing with One Volume Online at a Time (VMNT) 


IRAM files created with one volume online at a time must be processed in the same 
manner. . -_ 


Keyword Parameter VMNT: 


VMNT=ONE 


Specifies that only one elaine be processed online at any time. This parameter 
cannot be used if the MODE=RAND parameter is epi unless the INDX=YES 
parameter is also specified. 


13.4.25. Specifying Input or Output Record Processing in a Work Area (WORK) 


To specify that input or output records are to be processed in a work area rather than an 
|/O buffer area, you specify the WORK parameter. 
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Keyword Parameter WORK: 


WORK=YES " : a | a - _. 
May not be specified in the same ‘DTFIR- with the lOREG parameter. When you 
issue the input, output, or file addition operations: ‘you specify’ the address of the 
work area. The WORK parameter is required for indexed files when 
TYPE=OUTPUT or when TYPE=INPUT and ADD=YES. _ co = 


13.4. Ze: Nonstandard Forms of the = Rewore Parameters : 


OS/3 | eee management cesbes certain variant spellings for the Keyword parameters 
described in this section. These variations are: 


DTFIR | 0S/3 A 
Spelling = — Standard Form | 
BFSZ BLKSIZE/BKSZ 
EOFA EOFADDR 

ERRO ERROR 

INDA INDAREA 

INDS INDSIZE 

INDX INDEXED 

1OA1 IOAREA1 

lOA2 -.. » LOAREA2 

IORG IOREG 

KARG KEYARG 

KLEN — . KEYLEN 
KLOC  — KEYLOC. | 

OPTN OPTION 

RCSZ RECSIZE 
~SKAD SEEKADDR . . 
TYPE:..: TYPEFLE/TYPF | 
UPDT . UPDATE. 

VRFY VERIFY 


WORKA WORKA 
13.5.  IRAM KEYWORD PARAMETERS “— DD JOB CONTROL STATEMENT 
SUPPORT ONLY -_ oe a S eee 


The following keyword parameters can be specified only by using a DD job control. 
statement. eae 
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13.5.1. Variable Sector Support for IRAM Files (VSEC) 


In IRAM files, both the data and index partitions in the DTF specify a fixed sector size of 256 
bytes. This is required for the sectorized devices (8415, 8416, and 8418 disk subsystems), 
which are formatted for a 256-byte sector. The selector channel devices (8411, 8414, 8424, 
8425, 8430, and 8433 disk subsystems) have no such constraint. However, they are 
preformatted at OPEN time to accept the 256-byte sector size. This sectorization requires 
hardware overhead and thus decreases the effective capacity of the disk. 


Variable sector support eliminates the problem. It allows you to create IRAM files with data 
partition sector sizes larger than 256 bytes on the selector channel devices. Since the 
hardware overhead remains constant, the use of the larger sector size increases the 
effective capacity of the disk. 


To use variable sector support, you must specify it in a DD job control statement that you 
include in your job control stream when the file is created. The format of this DD job control 
statement is: 


// DD VSEC= b \ 
YES 


where: 


VSEC=n 
Specifies the sector size (number of bytes) to be used in creating the file. 


VSEC=YES 
Specifies that the sector size is to be computed at OPEN time, based upon record 
size and buffer size. The computed sector size will be the Jargest multiple of record 
size that does not exceed the buffer size. 


If you use a DD statement to specify a sector size for a file, the statement must be used in 
all subsequent job control streams that access the file, unless you specify the ACCEPT 
parameter in the LFD statement for the file. If you do, the DD statement that specifies 
variable sector Support may be omitted. : 


The message DM17 INVALID BLOCK SIZE SPECIFICATION is displayed if you use the VSEC 
ae incorrectly ina DD job control statement. This occurs us 


™ a sector size other than 256 bytes is eecatiad for a sectorized device; 


= the VSEC parameter specifies a sector size that is different from the sector size used to 
create the file; or 
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m changing the sector size results in the buffer size being less than the minimum buffer 
size required. To compnre the minimum buffer size, the tolowiing: rules apply: 


— If the record size divides evenly into the sector size, the minimum | buffer size ‘is 
. equal to the sector size. 


— If the record size is a ie of the sector size, the minimum buffer size is equal 
to the record size. 


— If neither of the preceding rules apply, add the sector size to the record size, 
subtract 1, and then round up to the next multiple of the sector size to find the 
minimum buffer size. 


13.5.2. File Recovery Support for IRAM Files (RECV) 


When you perform operations such as adding or updating records to a file, the physical file 
structure constantly changes during execution of your program. If your program runs to 
completion and the file is successfully closed, the file limits information contained in the file 
labels is updated. If a system failure occurs, the file is not closed and the file limits 
information is not updated. The effect of a system failure on a nonindexed file is that the file 
reverts back to its original state before it was opened. For example, added records are lost. 
In the case of an NGEXeS file, system failure may cause the file to be compromised; that is, it 


‘must be recreated. 


File recovery support eliminates these problems. It allows you to create IRAM files that can 
be reopened after system failure. It does this by updating the file limits information and 
writing it on the disk each time an operation that affects the information is performed. If you 
have specified file recovery and there is a system failure, you can reopen your: file because 
the file limits information was saved. 


To use file recovery support, you must specify a DD job control statement that you include in 
your job control stream when the file is created. The format for this DD job control 
statement is: 


// DD RECV=YES 


This statement is only valid at file creation time. It should not be included in the job control 
stream for subsequent jobs that process the file anes creation. 


If a system failure occurs during file creation, you will have to start over because the file 
creation program must run to completion and the file must be successfully closed before 
you can use the file recovery facility. If file creation is successful, the file recovery facility is 
activated each time you open the file. 


UP-8068 Rev. 4 - SPERRY UNIVAC OS/3 13-28 
BASIC DATA MANAGEMENT. 





If you are processing an indexed file (created with file recovery) where the physical file 
structure is changing and the structure modification process is interrupted by an operator 
cancel, HPR, or a hardware 1/O error, the file may be compromised. If the file is 
compromised and you attempt to reopen it, the error message DM66 FILE COMPROMISED 
is displayed to inform you that the file should not be used. If you want to open the file solely 
for reading its data contents in order to recreate the file, the file recovery support facility 
allows you to override the error condition. This is accomplished by including the appropriate 
DD job control statement in the job control stream when you reopen the file. The format for 
this DD job control statement is: 


// DD RECV=FCE 


This statement causes the file compromised error to be ignored. The message DM66 FILE 
COMPROMISED does not appear when the statement is present. The statement should not 
be used unless you receive the error message, and then on/y if you want to reopen the file 
to read its data contents in order to recreate the file. 


13.5.3. * Autonmade ‘Computation of - Initial Allocation roreeues De eels Files 
(AUTO) : 


Normally, when. an indexed IRAM file is eroated, 50% of the initial allocation is. assigned to 
the data partition, and 1% is assigned to the index partition.. The remainder is left as 
unassigned space to be used for logical extensions to the file. As the file is loaded, the data 
partition and the index partition are filled at different rates. This results in the two partitions 
extending on an alternating basis which, for large files, tends to rapidly use up the extent 
table entries. This causes the extent table to be exhausted and the error message DM45 — 
EXTENT TABLE EXHAUSTED. to be displayed. 


Automatic computation of initial allocation percentage helps minimize the problem. It 
causes the entire initial allocation to be assigned to the index and data partitions. in a 
calculated ratio based upon the record and key sizes. 


To use the automatic computation of initial allocation percentage, you must specify it ina 
DD job control statement that you include in your job control stream when the file is 
created. The format of this DD job control statement is: 


// DD SIZE=AUTO 


This statement is only valid at file creation time and has.no effect at other times. When it is 
encountered in the file creation job control stream for an IRAM file, this statement causes 

n% of the initial allocation to be assigned to the data partition and (100—n)% to the index 
partition. The value n is calculated at file open time and is dependent upon the record and 
key sizes. . é 
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There are two major factors that determine the accuracy of the calculated ratio: 


1. 


The manner in which the file is loaded: Space in the index partition is used more 
efficiently if the records are loaded in ascending key sequence rather than in unordered 
key sequence. 


The size of the file: Due to possible roundoff in the computation, the result is more 
accurate for relatively large files than for smaller files. For example, a given set of 
record and key lengths may yield a ratio of 3 to 1. For a 100 cylinder file, the allocation 
would be 75 cylinders for the data partition, 25 cylinders for the index partition. For a 
10 cylinder file, the allocation would be 8 cylinders for the data partition, 2 cylinders for 
the index partition. 
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13A. MIRAM Formats 
and File Conventions 


13A.1. GENERAL 


The multiple indexed random access method (MIRAM), a sixth disk access method in 
OS/3, is used for handling sequential, relative, and indexed files in programs that are 
written in the OS/3 1974 American National Standard COBOL language, and for 
sequential and relative (direct) files in programs that are written in FORTRAN IV language. 
MIRAM provides the same functions as those provided by OS/3 ISAM, ASAM, IRAM, 
SAM, and DAM disk access methods. A MIRAM file may reside on any of the disk 
subsystems used with OS/3, and it may occupy from one to eight disk packs, which must 
be of the same type. ; . 


The MIRAM processor can access only MIRAM characteristic files and IRAM characteristic 
files that it has created or IRAM files created by the IRAM processor. It cannot access disk 
files that have been created by the ISAM, ASAM, DAM, or SAM access methods, nor can 
MIRAM files be processed by these access methods. MIRAM files can be processed by 
using the sort/merge program, however, and by the data utilities program. 

A MIRAM characteristic file is one that meets any of the following conditions: 

= More than one key per record is permitted. 

= §=«6The file contains variable-length records. 

: Records may be logically deleted from the file (RCB is present). 


= Duplicate record keys are permitted, or key changes are allowed on update. 


= The length of a key in a record is one or two bytes. 
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An IRAM characteristic file differs from a MIRAM characteristic file in that it meets none 
of the conditions required for the latter; that is: 


# Only one key per record is permitted. 

= — The file contains fixed-length records. 

m Records cannot be logically deleted from the file (RCB not present). 

# Duplicate record keys or key changes during update are not permitted. 
# The minimum length of the record key must be three bytes. 


Note that IRAM characteristic files can be accessed by all programs that access IRAM 
files. 


The discussions that follow deal with MIRAM characteristic files. For information on IRAM 
characteristic files, refer to Section 12. 


13A.1.1. MIRAM Concepts 


MIRAM has a number of features and concepts that distinguish it from other disk access 
methods. 


= The data record slots in. MIRAM files, for either fixed- or variable-length records, are 

of uniform size and may span physical blocks, sectors, tracks, and cylinders as 

_ required. They may even extend from one volume to another (unless the file was 
created for processing only a single volume at a time). 


= Data records are written on disk compactly as a continuous string of bytes. 


= The string of data records can always be accessed sequentially (consecutively) or by 
relative record number. In addition, the data can be specified to be indexed by up to 
five keys; this causes MIRAM to build a suitable index structure for each key type ina 
partition separate from the data. 


# An indexed MIRAM file can be accessed by the additional random-by-key or 
sequential-by-key modes using a given key of reference, which can be changed. 


a Indexed MIRAM files, either multivolume or single-volume, may be created by means 
of an orderly load (records submitted in ascending key order) or a disorderly load 
(records submitted in no particular key order) and they may be extended by appending 
records in either manner. MIRAM does not sort the index at the completion of a 
disorderly load, but maintains the index current on a record-by-record basis. 


= =MIRAM files are always extended unless the INIT parameter is specified on the LFD job 
control statement of the device assignment set. The EXTEND parameter is not 
supported for MIRAM files. 
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= Duplicate keys are permitted. 


a When a new record has been added to an indexed or nonindexed file, it is 
nm pCiately available for retrieval. 


= Multivolume MIRAM- ies may be created for processing with either one volume 
online at a time, or with all volumes online. They must be processed in the same 
manner as they were created. 

# All programs that access a MIRAM file need not use the same data buffer size for 
input/output as was used to create the file. Those that access an indexed MIRAM 
file, however, must use the same index buffer size. 


= MIRAM allows you to logically delete records in your files; that is, it allows you to 
mark records so that in subsequent processing they will be ignored. 


= =MIRAM's restrictions are: 
- The maximum key length is 80 egies 
—No byte of a record key may contain the hexadecimal value ‘FF’. 


~ The minimum size for the index buffer is 256. bytes. 





13A.2. MIRAM FILE ORGANIZATION | 


All MIRAM characteristic files contain two partitions: the data partition, which MIRAM 
defines to the system access technique (SAT) as containing 256-byte unkeyed physical 
blocks, and the index partition, which is defined as containing 256-byte keyed blocks. If 
the file is a nonindexed file, the index partition is not used; that is, no entries will be 
placed in it and no space will be allocated to it. If the file is an indexed mle, entries will be 
placed in the index partition and space will be allocated to it. 


For indexed files, the data partition precedes the index partitions, which begins on a 
separate cylinder. 


-13A.2.1. The Data Partition 


The data partition is arranged in the same way for both nonindexed and indexed files. It is 
cylinder-aligned and consists of a single compact string of data records that may be keyed 
or unkeyed. The formats of the MIRAM data records are shown in Figure 13A-1. © 
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FIXED-LENGTH WITHOUT KEYS 52... oa Ps \/ 





VARIABLE-LENGTH WITHOUT KEYS 


ay 





LEGEND: 

rob = Record control byte (optional). Used to indicate that a record has been logically deleted from the file. For MIRAM 
fixed-length records, this byte is placed at the beginning of each record. For variable-length records, the third 
byte of the record descriptor word (RDW) is used as the rcb. 

R = Length of the logical record (RDW plus keys plus data). You specify this length as the number of bytes. For 


variable-length records, this value, expressed in binary, must be placed in the first two bytes of the RDW. 


Figure 13A—1. MIRAM Characteristic Data Record Formats (Part 1 of 2) 
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s, a RDW 4-byte record descriptor word for variable-length records. The first two bytes contain the logical record length (r) 


expressed in binary; the third byte may be used as the rcb; the fourth byte is not used. 


LA The starting location of record key n (n = 1 through 5) of a MIRAM file data record when the key does not start 
in the first byte of the record. L , represents the number of bytes (RDW plus data) that precede key n. The 
starting location of key n must be the same in each record. Key n must have the same length in each record (a 
minimum of 1 byte and a maximum of 80), and no byte may contain the hexadecimal value ‘FF’. 


S = Slot size. All records are written into fixed-size slots. Slot size equals the record size + 1 for fixed-length 
records with a record control byte; otherwise, slot size equals the record size. Slot size for variable-length 
records equals maximum record size + 4-byte record descriptor word. 


P = Padding. 


Figure 713—1. MIRAM Characteristic Data Record Formats (Part 2 of 2) 
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When data records are stored in a MIRAM file, the records are placed in uniform size 
record slots and are arranged in the same order you originally presented them to the 
MIRAM processor. These data records are stored in 256-byte physical blocks or sectors on 
your disk packs. Since the record slot size does not have to conform to the physical block 
or sector size, the records may span these physical boundaries as shown in Figure .13A-2. 


EXAMPLE 1 
PHYSICAL BLOCK 1.OR SECTOR 1 ‘PHYSICAL BLOCK 2 OR SECTOR 2 | PHYSICAL ‘BLOCK 3 OR SECTOR 3 
3 





EXAMPLE 2 





PHYSICAL BLOCK 1 OR SECTOR 1 PHYSICAL BLOCK 2 OR SECTOR 2 PHYSICAL BLOCK 3 OR SECTOR 3 
ge, Re eee, 
2 3 
EXAMPLE 3 


PHYSICAL BLOCK 1 OR SECTOR 1. ~~. PHYSICAL BLOCK 2 OR SECTOR 2 PHYSICAL BLOCK 3 OR SECTOR 3 





NOTES: 


1. All physical blocks or sectors are 256 bytes. 

2. 1, 2, 3... n represent record slots. 

3. Record slots in Example 1 are approximately 190 bytes each. 
4. Record slots in Example 2 are approximately 300 bytes each. 
5. Record slots in Example 3 are approximately 70 bytes each. 


Figure 13A—2. MIRAM Data Record Slots Spanning Physical Block or Sector Boundaries 


Your data records may also span track boundaries, cylinder boundaries, and volume 
boundaries (except when a multivolume file is created for processing with only one volume 
online at any one time). When new records are added to a file, they are appended to the 
existing data record string; that is, they are added at the end as a continuation of the 
original string. 
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13A.2.2. Entries in the Index Partition — 


If you have keyed records, entries are placed. in the index partition as these records are 
loaded into the data partition. MIRAM extracts all the keys from each record (a maximum 
of five keys is permitted) and constructs a 3-byte: pointer for each of the keys from the file 
relative record number of the position the record was written to. From these it forms an 
index entry for each of the keys in the record and stores them in the index partition. The 
index entry for each key consists of the key plus three bytes (it is equal to the specified key 
length plus three bytes) and it is stored in an area of the index partition, which is called a 
fine-level index. If you had three keys in each record, the index entry.for each key would 
be stored in a separate fine-level index; that is, the entry for key 1 would be stored in the 
fine-level index for key 1, the entry for key 2 would be stored in the fine-level index for key 
2, and the entry for key 3 would be stored in the fine-level index for key 3. 


A fine-level index is not formatted for hardware search, unlike the other levels of index 
that will be described subsequently. It is treated as a chain of multisector blocks where 
each sector is 256 bytes long. All entries in a fine-level index are maintained in ascending 
key order. Figure 13A—3 shows a typical fine-level index block of three sectors. 


CHAIN TO NEXT 






FLAG BYTE 
FINE BLOCK 
CURRENT NUMBER OF ACTIVE BYTES oN 
——S 


CONTROL AREA 

1S LAST SIX > 
BYTES OF INDEX 

BLOCK 






ACTIVE ENTRIES 





CONTROL AREA 


Figure 13A—3. Fine-Level Index Block 


spe 
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When a fine-level index is created, another hierarchical level of index is always created - 
the coarse-level index. This is hardware searchable and :is composed of 256-byte blocks 
that contain entries similar to those in the fine-level index. They differ, however, in that 
the 3- byte pointer in each coarse- level entry does not represent the file-relative number of 
a record in. ‘the. data partition. Instead, it points to another index block at a lower level - 
either a fine-level block or a block in what is called a mid-level index. Another difference is 
that instead of having a 6-byte control area, each coarse-level block uses its final byte to 
indicate the number of active entries. The entries in a coarse-level block are filed in 
descending key order. The high key of the block is the first one encountered by the 
hardware search and its length is equal to the longest key in the group plus four bytes. 
Both the coarse-level and mid-level blocks have the same format (Figure 13A-4). 


ACTIVE ENTRIES INACTIVE AREA 
oe 


SECTOR 





~ Figure 13A—4. Coarse- or Mid-Level Index Block 
13A.2.3. MIRAM Index Structure 


As you know, you can specify up to five keys for a file. For each key that you specify, the 
MIRAM processor will build a separate index structure..In those cases where you have 
more than one key, these separate index structures will allow you to use any of the key 
types as the key of reference to access your data records. when you subsequently use the 
file in a program. . | 


When the MIRAM processor builds an index structure for your file, it creates a minimum 
of two levels of index: a fine-level index and a coarse-level. index. If your file is very large, 
one or more mid-level indexes are created as needed. The fine-level index consists of one 
entry for every record in the data partition of your file..The fine-level entries are filed in 
ascending key order until an index block (256 bytes) is filled. At this time, one coarse-level 
entry is made that points to the high key entry of that filled fine-level block. As.each fine- 
level block is filled, another coarse-level entry is made. This process continues until all 
your records are on file. : 


The coarse-level index is automatically allocated by MIRAM. Its size is always one track | 
regardless of the type of disks being used. If the coarse-level index is filled before all your 
records are on file, a mid-level index is created. The MIRAM processor allocates two 
tracks, designates them as a mid-level index, and copies the entries from the coarse-level 
track onto these tracks. It then places two entries in the coarse-level index. Each entry 
points to a high key in one of the tracks in the mid-level index. In this manner the entries 
on the coarse-level track are replaced by two entries. As new fine-level entries are 
recorded, one entry is made in the coarse-level index for each filled index block in fine- 
level index and when the coarse-level index is filled a new mid-level index is created just 
as before. This process continues until all records are on the file. Figure 13A-5 shows the 
structure of a MIRAM index. 
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- COARSE.LEVEL ; 1: TRACK ; Neu a! 


MID-LEVEL | “ : | ADD 2 TRACKS AT A 
(IF NECESSARY) _ TIME AS NEEDED 


ONE ENTRY FOR 
EVERY RECORD IN 
DATA PARTITION 


FINE LEVEL: 





Figure 13A—5. MIRAM Index Partition — 


13A.2.4. Retrieving Records from an indexed MIRAM File 

To show how records are retrieved from an indexed MIRAM file, assume that a file with a 
4-level index has been created. A search for a specific data record by key in this case 
would proceed as follows: 

= the search begins in the coarse-level index, —_ 7 . or . sail 
a 6a hit is made that seins to the first mid-level index; — . te 

= the new mid-level is searched; | 

# a hit is made that points to the second mid-level index; 

= the second mid-lével is ‘Searchétt 

# a hit is made that veut to the fine-level aes 

m the fine-level is searched; 

= §=6a hit is made that points to the data record in question; and 


= the data record is retrieved. 
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13A.2.5. Estimating Disk Space Required for an Indexed MIRAM File 

The following procedure will allow you to estimate the number of cylinders for your 
primary allocation of disk space to an indexed MIRAM file. The result is a good 
approximation that you can use in specifying the EXT statement in the job control device 
assignment set that allocates disk space for an indexed MIRAM file to be created by your 
program. This procedure can also be used to determine the number of cylinders to be 
allocated for an indexed MIRAM file that is to be generated from another file by the OS/3 
data utility program. | 

The number of cylinders required for an indexed MIRAM file includes those occupied by 
the data partition and the index structures for each key type in the file. To estimate the 
number of cylinders the file will require, proceed: as follows: 

First, calculate D, the number of sectors required for your data records (the data partition). 
Step 1: 


D = record-length - number-of-records 
Ss 


where: 
S is the sector size. The default size is 256 for all types of disk subsystems. For 8411, 
8414, 8424, 8425, 8430, and 8433 disk subsystems, this value can be greater than 
256. 

Next, calculate B;, the number of index blocks required by your fine-level index for key,. 


Step 2: 


B | = number-of-records * (keylength; -r_3) ° (=) 
(256 - m) — 6 3/ 


where: 
_ the factor of 4/3 is used because the average fine-level index will be 3/4 full. 
m is the number of 256-byte sectors in the index buffer. (See 13B.3.1.) 


Then calculate F;, the number of 256-byte sectors required by your fine-level index for 
keyj. 


Step 3: 
Fy — mM ° Bi 


Repeat steps 1 through 3 as many times as necessary and then calculate F, the number of 
256-byte sectors required by your fine-level indexes for all keys in the file. 
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Step 3a: 


where: | 

n is the number of keys in the file. 
Then perform the final calculation. This calculation, which is the sum of the data 
requirements and the fine-level index requirements, represents over 95 percent of the 
space required for an indexed file. Once this is determined, it is a simple matter-to figure 


out what your space requirements are for a given file. 


Step 4: 





c= : 
U-N * A-N 
uo YD YO Zt 
where 
C 
Is the number of. cylinders to allocate to. the indexed MIRAM file. 
A 
Is the disk dependent number of 256-byte sectors per track for data partition 
- (Table 13A—1). . 
D 
Is the number of 256-byte sectors required for the data partition. 
F : : 
Is the number of 256-byte sectors required by all the fine-level indexes. in 
the file. 
Is the disk-dependent number of 256-byte sectors per track for index 
partition (Table 13A—1). 
N. 


Is the disk dependent number of tracks per cylinder (Table 13A—1). : | 
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Example: 


Assume that you want to calculate the number of cylinders to allocate for an indexed 
MIRAM file and the following conditions apply: 


Number of records 77,500 
Record length 512 bytes 
Keylength, 28 bytes 
Keylength, 30 bytes 


Sector size (data partition) 256 bytes 


Index buffer length | _. 512 bytes 
“Type of disk 8433 
= D- = record length - number-of-records | 
256 
= 512 - 77,500 
256 


155,000 sectors for data partition. 


= B, = _ number-of-records - (keylength, + 3) - (3) 
(256 - m) - 6 3 


= 77,500 - (28 + 3). (4) 
(256-2)-6. \3 


= 6331 index blocks required for the fineciavel fides tor kev: 
a Fi, = mB, 

= 2- 6331 
= 12,662 sectors for the fine level index for key. 


"= 8, = number-of-resords ~(keylength +3) (4°) 
(256 - m)- 6 3 


= 77,500 - (30 + 3). (4) 
(256 - 2) - 6 3 


= 6739 index blocks required for the fine-level index for key. 


14 
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ad F. = m- Bo 
= 2: 6739 


= 13,478 sectors for the fine-level index for key>. 


MS 


F 
1 


I 


= F,+F, 
= 12,662 + 13,478 
= 26,140 sectors for all the fine-level indexes for all keys in the file. 


= ## The maximum coarse-level index on an 8433 disk can contain 132 sectors. As you 
can see, this number is too small to contain all of the index blocks for either of the 


keys. 
a Cc = F D 
U:-N * A-N 
= (26,140 + 58 + 2090) a 155,000 
29:19 33-19 


= 299 cylinders to be allocated to the file. 
NOTE: 


After you have calculated your disk space requirements and you proceed to create your 
file, you must provide enough volumes to hold the file. This must be considered because 
the amount of space available is not the same for all types of disk. Refer to Table A—4 to 
determine how many volumes you will eee based upon your calculations and the type of 
disk you intend to use. 


13A.2.6. Estimating Disk Space Required for a Nonindexed MIRAM File 


The following procedure will allow you to estimate the number of cylinders required for 
your primary allocation of disk space to a nonindexed MIRAM file. First, you must calculate 
D, the number of 256-byte sectors required for your data records (13A.2.5). Then, divide by 
the product of A times N (from Table 13A—1). 


UP-8068 Rev. 4 SPERRY UNIVAC OS/3 13A-13 
BASIC DATA MANAGEMENT 


Se a eEnDrmnnnmnmsnmn as mee sr teeeneneumetut eae ened 


Table 13A—1. Disk-Dependent Factors for Determining Disk Space Requirements 


U A 
SPERRY UNIVAC (Number of 256-byte (Number of 256-byte 
Disk Subsystem sectors per disk track sectors per disk track 
for index partition) for data partition 


N 
(Number of tracks 
per disk cylinder) 





*Removable portion 
**Fixed portion 


RYU 
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13B. Functions and Operations 
of MIRAM 


13B.1. GENERAL 


Before you create a MIRAM file (a MIRAM characteristic file unless noted otherwise) you 
must carefully consider how you will use the file in subsequent programs because this 
governs how it should be created. If you expect to process unkeyed records consecutively 
or you need to access specific records quickly without processing the preceding ones, the 
file should be created as a nonindexed file. If you intend to process keyed records either 
consecutively or randomly, the file should be created as an indexed file. 


After you have created a MIRAM on file, you can perform retrieval, update, and other 
operations either consecutively or randomly, or you can switch back and forth between 
consecutive and random operations. Both nonindexed and indexed MIRAM files that span 
two or more volumes can be created with only one volume online (mounted) at a time, or 
with all volumes online. A multivolume file must always be processed in the same way it 
was created; only one volume is online at a time, or all volumes are online. 





The discussions that follow are at a general level. For details of the actual programming 
statements you use for creating and processing MIRAM files in OS/3, refer to the OS/3 
1974 American National Standard COBOL programmer reference, UP-8613 (current 
version), or the OS/3 FORTRAN IV supplementary reference, UP-8474 (current version). 


13B.2. PROCESSING NONINDEXED MIRAM FILES 


A nonindexed file is one that is organized consecutively.-Its records are written on the disk 
in the physical order they are presented to the MIRAM processor. The records are 
processed consecutively in the order they appear on the disk. A nonindexed file can also 
be one that is organized relatively; each record in the file is written on the disk in a 
specific position relative to the beginning of the file (independent of the order in which 
they are presented to the MIRAM processor). This allows any record in the file to be 
retrieved directly without processing any preceding records when the location of the 
record is specified. 


The following subsections describe the general procedures for creating and processing 
co nonindexed files. 
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13B.2.1. Creating a Sequential MIRAM File oe 


If you want to create a file for sequential processing, you must define the file as a 
sequential output file in your program: You must also specify the uniform size of your 
record slots and the size and address of your data buffers (I/O areas). If you have variable- 
length records, the slot size must be large enough to hold the maximum size record plus 
the required 4-byte record descriptor word (RDW). You may use two data buffers, each 
half-word aligned, but they must be contiguous and the same size. The minimum data 
buffer size that you can specify for your program is determined as follows: 


a If the slot size divides into 256 without remainder, the minimum buffer size is 256 
bytes. 


w §6If the slot size is a multiple of 256, the minimum buffer size is equal to the slot size.. 


a lf the slot size does not divide into 256 without remainder and is not a multiple of 
256, add 255 to the slot size and round this sum arene) to the next multiple of eae 


(Note that for fixed-length records, the slot size + 1 must ‘be: used in your Butter 
calculation: This is required because space must be provided in the buffer for the extra 
byte, the RCB, that is appended to the front ofeach: fixed-length record by the MIRAM: 
processor and is not counted when you specify your slot size.) 


This calculation also applies when you create relative or indexed files. If you specify data 
buffers larger than the minimum, you may improve your program’s performance. Note that 
when a file is processed in subsequent programs, you do not have to specify the same 
data buffer size that you used to create the file, but it must be at least the minimum. 





After you open the file, you submit your records, one after the other, until you have no 
more records. The records are stored in the data partition in the order you submitted them. 
When the file is subsequently processed, it is processed in the same order. The MIRAM 
processor records the relative record number of the last record written in the file control 
table and the volume table of contents. 


13B.2.2. Extending a Sequential MIRAM File 


Once a sequential file has been created, it can be extended (enlarged) only by appending 
new records at the end of the existing data string. Records cannot be inserted between 
existing records nor can they be appended during retrieval or update operations. : 


Extending a sequential file is essentially the same process as creating the file because the 
same specifications are made. The difference is that you must define the file as a 
sequential file that is to be extended rather than a sequential output file. After you open 
the file you submit the new records, one after another, as in file creation, and they are 
stored in consecutive order starting after the last record of the existing data string. 


—— 
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13B.2.3. Adding Records to a Sequential MIRAM File 


If you want:to enlarge a sequential file by inserting records between existing records or 
appending records at the head of the existing data string, you must use some other 
processor..A way to solve this: problem is to sort the new records into the consecutive 


sequence you expect :to process them, and then use them as an input file (together with 
you sequential MIRAM file) to the sort/merge program or the data utilities program to 
create a new sequential file with the new records in the proper order. Refer to the 
sort/merge user. guide, UP-8342: (current = version) or. the data utilities user 
aides Bhs aint PEISPenCe, a 8069 (current en for details. : 


13B.2.4. Retrieving and Guana nesbide in a Sequential MIRAM File. . 


You can.-retrieve records or retrieve and update records in sequential (consecutive) order in 
a sequential file. For sequential retrieval, you must define the file as a sequential input file 


in your program. For sequential retrieval and update, you must define the file as a 


sequential file for update. You can provide two data buffers. If you do, the lengths of these 
buffers, need not be the same as the data buffer. that was used to create the file. However, 
if two buffers are used, each one must be the same size as the other. 


The MIRAM processor will provide the records in the same order that they were written on 
disk when the file was created or extended. Consecutive retrieval will continue until you 


close the file or the end of file is reached. If the file is to be terminated by end of file, you 


must have specified the address of a routine for handling this situation in your program. 
Records may~ not be. Ppneniee SURI peMlen ay Operations or retrieval and: spots 
ORerallens:: | 


13B.2.5. Deleting Records from a Sequential MIRAM File 


If a MIRAM file is defined as a sequential file in your program, you cannot logically delete 
records from your file (mark specific records so they will be bypassed when the file is 
processed in subsequent progialne). te delete records, the file must have been created as 
a relative file. : ; ee ot pete “8 ia 


13B.2.6. Reorganizing a Sequential MIRAM File. 


At some point you may want to reorganize a sequential file. Perhaps your experience in 

using the file has shown that a different physical sequence of records would be more 
convenient. There are two methods that you. can use to reorganize your file — the 
sort/merge program or the data utilities program. Either of these will accept your file as 
input and resequence the data records..For details, refer to the sort/merge user guide, 
UP—8342 (current version) or. the data utilities user guide/programmer reference, 
UP—8069 (current version). - 
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13B.2.7. Creating a Relative -MIRAM File — -° 


If you require a file in.which each data record is to be assigned to a specific position on 
disk, you must create a relative file. You do this by defining the file as a relative output 
file. You. must also specify the uniform size of your record slots and the size of your’ data 
buffer. The minimum data buffer calculation is-the same as Ss that described for a eeqHentic! 
tle in- ada i: “3 


After you open Wine file, you pseeat each record, one by one, to ifs MIRAM processor ina 
work area you have defined along with the file relative position the récord is: to occupy. 
This position is not a disk address. It is a 4-byte file-relative number (relative to the 
beginning of the file; position 1 is relative record number 1, etc) that you supply in a field 
you have defined before you issue the output function to write the record to disk. 


The ‘method. you use to determine the relative record number that you assign to each 
record is up to. you. It can be a potential source of trouble if you are not careful; the 
method you use may generate a relative record number of'a record that has. already been 
placed on the file. If an output function is issued in this situation, the ‘attempt to place the 
new record in an occupied position will be rejected and an error condition will result. 


13B.2.8. pending: a RGIENINe ee rie — 


Evendina a relative file is Suscntialiy the. same as. seating it. Vau spouide each record to 
be placed in the file in a work area, and you supply the relative record address for the 
record in a predefined field before you issue the output function. If you direct a record to a 
point beyond the current file end (established at file creation: that is, the relative record 
address of the last valid record on the file), any gap will be filled with void records. If you 
direct a record to a position short of be file end, the eboreucn will be pelected =! if ‘it is 
occupied by a valid record. Re 


138, 2. 9. Retrieving and Updating Records ina Relative MIRAM File 


You can retrieve ee or retrieve and update records! 3 ina aienve file: ssaudatislly 
(consecutively) or randomly by relative record number. You also have the ability to switch 
retrieval methods (between sequential and random retrieval), and to mepecity at what sau 
you want to commence sequential retrieval. 


For sequential retrieval, define the file as an input file for sequential processing. For 
retrieval with update, define the file as an update file. When you: issue an input function, 
retrieval begins euro meleeey with the first oe position ‘in the file. 


If you do not want to begin your sequential: processing with the first record, you can issue 
a function that establishes the starting point. This must be done after the file has been 
opened and before you issue an input function. To establish a starting point, you must 
place a relative record number in a predefined field in your program and then use the 
starting point function to specify where the starting point is to be; that is, the starting 
point is equal to, greater than, or not less than the relative record number you have 
supplied. Your first input function retrieves the record at the starting point. The 
subsequent input functions will retrieve the records in consecutive order. You can change 
the starting point at any time while the file is open. 





& 
a 


at 
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For random retrieval by relative record number, define the file as an input file for random 
retrieval. For retrieval with update, define the file as an update file. For random retrieval, 
you must supply the relative record number of the desired record in a predefined field in 
your program before you issue an input function. If you update a retrieved record, the 
output function to rewrite this record does not require you to supply a relative record 
number. 


13B.2.10. Deleting Records From a Relative MIRAM File 


If you want to logically delete records from a relative file, you must define the file as an 
update file. After the file is opened, you can delete a record by first issuing an input 
function for that record, and then following this with a delete function. The delete function 
logically deletes the record by marking it as a void record. (The record is not physically 
removed from the file.) The marking process consists of setting the high order bit in the 
RCB. 


When a deleted record is encountered in subsequent sequential processing, it is bypassed. 
If you are retrieving records randomly and you specify the relative record number of a 
deleted record, it is treated as a no find. 


13B.2.11. Reorganizing a Relative MIRAM File 


If you want to reorganize a relative file, you cannot do it in a straightforward manner. For 
example, if you have logically deleted records in a relative file and you use the data utility 
program to remove the invalid records and recopy the file, the relative position of the valid 
records will change. This occurs because the valid records are copied in the same 
consecutive order that they appeared on the old file. As a result, any subsequent 
processing of the new file may prove unsatisfactory because the valid records will not be 
where they originally were. 


A possible solution would be to use the data utility program to remove the invalid records 
and copy the valid records to a sequential file. This sequential file could then be used as 
input to a relative file creation program that will place the valid records in the positions 
you want them to be. 


13B.3. PROCESSING INDEXED MIRAM FILES 


An indexed MIRAM file contains a data partition with the data records ordered 
consecutively in the order that you submitted them, and an index partition that consists of 
one or more index structures arranged in ascending key order. The number of index 
structures is governed by the number of keys specified for the file. Each data record can | 
contain from one to five keys (uniform length character strings that uniquely identify the 
record). A key may start at the head of the record or may be embedded within it; however, 
the location of each key type must be the same for all records in the file. Duplicate key 
values are permitted. | 
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When you create an indexed file for processing one volume online at a time or with all 
volumes. online, you can submit your records to the MIRAM processor as an orderly load 
or a disorderly load. The former means that the data records are submitted in ascending 
key order and the latter that the records are submitted in any other order. In both cases, 
the records are placed in the data partition in the order submitted; however, the keys are 
always arranged in ascending key order in the index structures. The following subsections 
describe the general procedures for creating and processing indexed files. 


13B.3.1. Creating an Indexed MIRAM File 


To create an indexed MIRAM file you must define the file as an indexed output file in your 
program. You must also specify the following: 


= uniform size of your record slots; 

m the size and address of your data buffers; 

z the length and location of all keys in your records; 

= the size and address of your index buffer; and 

m =§«the address of a field in your program that is to contain a search key. 


If you have variable-length records, the slot size must be large enough to hold the 
maximum size record plus the required 4-byte record descriptor word (RDW). You may use 
two data buffers (each half-word aligned), but they must be contiguous, the same size, and 
they must immediately follow the index buffer. The minimum data buffer calculation is the 
same as that described for a sequential file in 13B.2.1. 


The index buffer is also half-word aligned and must be at least 256 bytes in length. It 
can be larger; however, if it is, it must be a multiple of 256 bytes up to a maximum of 
32,512 bytes. The index buffer must immediately precede the primary data buffer. A 
good rule to apply when determining your index buffer size is to multiply the sum of the 
largest specified key plus 3 bytes by 20, rounding the result up to the next multiple of 
256. 


The length of the field that is to contain a search key must be equal to the length of the 
largest key in your file plus three bytes. 


After you open the file, you present each record to the MIRAM processor in a work area 
you have defined, and then you issue an output function to write the record to disk. 


13B.3.2. Extending an Indexed MIRAM File 


Extending an existing indexed file is essentially the same process as creating the file. As 
in creating the file, you present each record to the MIRAM processor in a work area you 
have defined and then you issue an output function to write the record to disk. The 
records are appended to the end of the data string in the data partition. Your records can 
be submitted as an orderly load or a disorderly load. In either case, the records are placed 
in the data partition in the order submitted and the record keys are placed in the index 
structures in ascending key order. After a record has been successfully added to the file, it 
is immediately available for retrieval because the index structures are updated each time a 
record is added to the file. 
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13B.3.3. Retrieving and Updating Records in an Indexed MIRAM File 


You can retrieve records or retrieve and update records in an indexed file sequentially 
(consecutively) or randomly by key. You also have the ability to switch retrieval methods 
(between sequential and random) and to specify at what point you want to | commence 
sequential retrieval. 


For sequential retrieval, define the file as an input file for sequential processing. For 
sequential retrieval with update, define the file as an update file. 


After the file is opened, the sequential position is established at the lowest key value in 
the keyi index structure. If you want a different starting point, you must establish a new 
starting point (the value of the record key at which retrieval is to begin). To do this, you 
must place a key value in a predefined field in your program and then use the starting 
point function to specify where the starting point is to be; the starting point is equal to, 
greater than, or not less than the key value you have supplied. Your first input function 
retrieves the record at the starting point and the subsequent input functions will retrieve 
the records in consecutive order. 


After a Sequential by key retrieval sequence has been started, you can continue it until: 
# you reach the end of file or the end of volume; | | 

= you specify a ae ee point; 

# you change the file processing mode from sequential to random; or 

= you close your file or it is closed as the result of an error. | 


For random retrieval by key, define the file as an input file for random retrieval. For 
retrieval with update, define the file as an update file. For random retrieval you must 
supply the key of the desired record in a predefined field in your program before you issue 
an input function. If you update a retrieved record, the output function to rewrite this 
record does not require you to supply a key value. 


If you are performing a sequential retrieval sequence and you interrupt it to perform a 
random retrieval operation, the sequential retrieval sequence cannot be resumed at the 
point it was interrupted (unless random retrieval with hold is requested). —— 


If you have specified that duplicate keys are permitted and you are performing a sequential 
retrieval sequence, records with duplicate keys will be retrieved in the order they were 
presented to the file during file creation. If you perform a random retrieval, the first record 
encountered in a duplicate key series that contains a key equal to the search key will be 
retrieved. 
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13B.3.4. Adding Records to an Indexed MIRAM File during Retrieval 


You can add records to an indexed file during retrieval if you have defined the file as an 
update file. To add a record during retrieval you must provide the new record in a 
predefined work area in your program, and then issue an output function to place it in the 
file. The record will be placed in the file if the value of the record key is less than or 
greater than any key in the file, or it falls within the range of the existing keys. If you have 
specified that duplicate keys are not permitted, the record will be rejected if its record key 
duplicates the key of a record that is already in the file. 


If you interrupt a sequential retrieval sequence to add a record, the sequence will be 
resumed at the point it was interrupted when you issue the next input function. 


13B.3.5. Deleting Records from an Indexed MIRAM File 


If you.want to logically delete records, you must define the file as an update file. After the 
file is opened, you can delete a record by first issuing an input function to retrieve the 
record and then follow this by a delete function. The delete function logically deletes the 
record by marking it as a void record. (The record is not physically removed from the file.) 
This marking consists of setting the high order bit in the RCB. 


When a deleted record is encountered in subsequent sequential processing, it is bypassed. 
If you are retrieving records randomly and you specify the key of a deleted record, it is 
treated as a no find. 


13B.3.6. Reorganizing an Indexed MIRAM File ~ 


Your experience in -processing an indexed file may indicate that the file should be 


reorganized. For example, your processing may have logically deleted a large number of 


records and you want to compress the file by physically removing these records. Another 
reason to reorganize, is that the file was created or extended with disorderly load, and you 


want to improve your program’s performance because the majority of your processing. 


involves sequential retrieval. 


In the former case, you can use the data utility program to delete the invalid records. In 
the latter case, you can use the sort/merge program to sort your data records in 
ascending key order. For details refer to the data utilities user guide/programmer 
reference, UP- 8069 (current version) or the sort/merge user guide, UP-8342 (current 
version). 


13B.4. DEFINING AN OS/3 MIRAM FILE (DTFMI) 


The DTFMI declarative macro is used to define a MIRAM file. It establishes a 388-byte file 
table. 


Normally, you do not need to know what the format of the DTFMI macro is because the 
file definition statements you use in your program are effectively translated into a DTFMI 
macro. 


esas 
pee X 
\, 
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lf, however, you want to temporarily change your file definition at run time by using a DD 
job control statement, you must know what the format is. To help you in these cases, the 
DTFMI macro format and a summary of the keyword parameters (Table 13B—1) that 
indicates which parameters can be changed by the DD job control statement are provided. 
Examples of typical DTFMI macros follow Table 13B—1, and: detailed descriptions of the 
individual DTFMI Keyword, parameters are DEOVIERS in 13B. oa 


Format: a | 
LABEL -— NoperationA aes OPERAND 
filename DT FMI fC EXE 
i _ ) EXCR 
ACCESS= ) oo 
SRDO ) 
BFSZ=n ) 


[ EOFA= symbol] 

[,ERRO= symbol] 

[, INDA=symbol] 

L,INDS=n]~ 

| ,10A1=symbol 

~ L1OA2=symbol] 
[IORG= (r)]- pa 
[,KARG=symbol] 7 a 

:xeven (ao fSoe"y] eae] 


[,LOCK=NO] 


ooe= | RAN i 
~ C RANH 


[,OPTN=YES] 


[pRoc- LUNK \] 


:, RCB= -NO] 


; [RCrM- {ia |) | | 


.RCSZ=n . 


| mere ) MOD i | 
. \ REP )_ 


,KAD=symbol 
[, VMNT=ONE] 
[ VRFY=YES] 
[| WORK=YES] 
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. Table 13B—-1.. Summary of DTFMI Keyword Parameters (Part 1 of 2) 



















_ Nonkeyed 
’ Opera- 
tions » 


Specifi-- 
cation | 














Keyword ' "Restrictions Remarks 


This DTF: read/update/add use . 
Other jobs: no access 


ACCESS* 


ee ad 
aac 


This DTF: read use 


Other jobs: read/update/add use 





This DTF: read use 
Other jobs: read use 


Always required Supplies data buffer size 
te i Address of end-of-file routine 
[-e-= - Address of error handling routine 


Used only with keyed Address of index buffer 
operations 


Used only with keyed Indicates size. of index buffer 
- operations 
Always required Address of primary data buffer 


Only allowed with sequential Address of secondary data 
output or unkeyed sequential buffer 







IORG (r= Not permitted when Indicates |/O buffer index 
i K=Y¥ register 
KARG symbol . x Used only with keyed Address of field that contains key 
operations of desired record 


KEYn** Used only with keyed Indicates key length, key 
operations. location, and whether duplicate 
n>1, key length <3, keys or changes to keys are 
duplicate keys, or changes allowed 
to keys not permitted 
for RAM characteristic 
files. 


MODE aa file processing 
(default) 


Random J Random file processing =| J Random file processing =| 


RANH Random file processing (hold sequential 
position) 


| oPTN | | Optional file | Optional file 


PROC Keyed (index and data) operation 
(default) 


Nonkeyed (data) operation 





oa 
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Table 13B—1. Summary of DTFMI Keyword Parameters (Part 2 .of 2) 








iS nec Nonkeyed | 
Keyword gon Opera- Restrictions Remarks © 
cation . be 
-tions. 
RCB Oo “Required for RAM) No record control byte 


characteristic files 


Not permitted for RAM 
characteristic files 


RCSZ* n Always required ~~ 


INF | Update not alened, 


‘Variable- length records 


Indicates record ‘size 


Retrieval for 
information (default) 


Address of seek . as 
address field ae 


















Always. required 


Check parity of output records 
after they have been written | 





















Defines file to be processed 
_ with only one volume 
online at a time 


Nonkeyed random operations 
and random output - 
operations not allowed. 









Required for all output, 
keyed update, and delete 
functions 


indicates that record processing 
is in a work area 









LEGEND 

16) = Optional 
R = Required. 
$ = Select one 
Xx -= Not used 


*Parameter may be changed on DD job control statement. 
**Parameter may be changed on DD job control statement for indexed file only. 


PPR, 
“ee _ 


13B-12 >. 


SPERRY UNIVAC OS/3 
BASIC DATA-MANAGEMENT .- 


UP-8068 Rev. 4 


Example (MIRAM Output File): 


PorcRe VON 


10 


OPERAND 


LABEL 
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13B.5. DTFM!I KEYWORD PARAMETERS 


The following paragraphs discuss how each of the DTFMI keyword parameters are used. 


13B.5.1. Specifying File Accessing Options (ACCESS) | 
See 11.4.1 for a detailed explanation to the ACCESS keyword parameter. 


Note that indexed files should not be shared in an environment that permits only one writer to 
a file but any number of readers. If a file is shared, the readers may get unpredictable results; 
that is, DM24, DM39 error messages or no-find errors may result when attempting to read 
records that were previously accessible. Consequently, the ACCESS=EXCR or ACCESS=SRD 
specification should not be made for an indexed file in either the DTFMI declarative 
macroinstruction or the DD job control statement. 


Records added by the writer (ACCESS=EXCR) to a nonindexed file, in a shared 
environment that permits one writer and any number of readers, are not available to the 
reader (ACCESS=SRD). Once the writer closes the job, any added records will be available 
to users who subsequently open the file. 

13B.5.2. Specifying the Buffer Size for a MIRAM File (BFSZ) 

The BFSZ parameter specifies the size of the data buffer in the file. 


Keyword Parameter BFSZ: 


BFSZ=n 
Is always required. n represents the number of bytes in the data buffer. The size 
must be at least 256 bytes as well as a multiple of 256. To calculate the 
minimum buffer size, see 13B.2.1. 


13B.5.3. Specifying the End-of-File Handling Routine (EOFA) 
When data management senses the end of data while you are processing a MIRAM file 
sequentially by key or consecutively, it looks for the symbolic address of your end-of-file 
handling routine and transfers control to that address. 
Keyword Parameter EOFA: 

EOFA=symbol 

Specifies the symbolic address of your end-of-file handling routine. 

13B.5.4. Specifying Error Handling Routines (ERRQ) 


When data management detects any error or exception in processing, it looks for the 
symbolic address of your error handling routine. 
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Keyword Parameter ERRO: 


ERRO=symbol : 
Specifies the symbolic address of your error handling routine to which data 


management transfers control when an error is detected. When control is 


transferred to this routine, filenameC contains information on the reasons for the 
error (see Tables B—1 and B—3). If this parameter is omitted, control is returned 
to your program inline. 


13B.5.5. Naming the Main Storage Area for Index Block Processing (INDA) 
During keyed operations, index blocks are processed in a main storage index area. 
Keyword Parameter INDA: 


INDA=symbol 

Specifies the symbolic address of the main storage area in which index blocks 
are processed. This area must be half-word aligned and must immediately 
precede the primary |/O (data) buffer area 1|OA1. This parameter is required for 
all keyed operations and it requires that all related keyword parameters must be 
specified: INDS, KARG, and KEYn.:If INDA is specified and any of the related 
parameters are omitted, it is assumed that indexed operations were not intended 
to be used, and none will be permitted. . 


13B.5.6. Specifying the Index Area Length in Main Storage (INDS) 


When indexed files are processed, the index blocks are processed in the index area 
specified by INDA. The length of this area must be specified. 


Keyword Parameter INDS: 


INDS=n ; | 

Specifies the auiabes of Biles: to be ised in main storage for the index area 
named in the INDA parameter. The length must be at least 256 bytes or a 

- multiple of 256 up to a maximum of 32, ould bytes. This parameter is raauinge 
for all indexed files. | 


13B.5.7. Identifying the Primary Data Buffer (1OA1) 


When any file is processed, at least one data buffer is required and this area must be 
identified. 


Keyword Parameter IOA1: 


10A1=symbol 


Specifies the symbolic address of the primary data buffer. This area must be half- - 


word aligned, greater than or equal to 256, a multiple of 256, and it must be 
consistent with the BFSZ parameter. It must immediately follow the index area 
(INDA) if specified, and must immediately precede the secondary data buffer 
(IOA2) if specified. 


~~. 


eo 
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13B.5.8. Identifying the Secondary Data Buffer (lOA2) 


If you want to use double buffering to improve the performance of your preg aly you can 
specify an additional buffer in certain cases.. 


Keyword Parameter IOA2: 


1OA2=symbol 
Specifies the symbolic address of a secondary data buffer. As with IOA1, this 
buffer must be half-word aligned, the same size as 1OA1, and must immediately 
follow the primary buffer (IOA1). You can use a secondary data buffer only when 
- performing keyed or ee sequential al or nonkeyed seguenue input 
operations. . 


13B.5.9.. Pointing to the Current Data Buffer (lIORG) 


If you are not referencing records in work areas, you must specify a data patee index 
register number. 


Keyword Parameter IORG: 


lIORG=(r) 
Specifies the number of the general register to be used to point to the current 
data buffer when you do not reference records in the work area. Registers 2 
through 12 may be used. Either IORG or WORK must be ‘specified. If both are 
specified, the WORK parameter is used. 


13B.5.10. Naming the Key eumen rele (KARG) 


If you are using keyed operations, you must name the location in your Progra Nhers gids 
will place the search key for record retrieval. 


Keyword Parameter KARG: 


KARG=symbol 
Specifies the symbolic address of the field in you program where keys are placed 
to effect the retrieval of records. The length of this area must be equal to the 
largest key in your program plus 3 bytes. This parameter is required for all eevcr 
operations. 
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13B.5.11. Specifying the Keys for an Indexed File (Keyn) 


When you process an indexed file, you must specify (for each key in your records) the 
length, location, if duplicate keys are permitted, and whether the key may be changed 
during update. 


Keyword Parameter KEYn: 


ete UE Resa [iN ener) 

, DUP ) CHG : 

-»-. Specifies one of up to five keys for an indexed file; that is, 1< n< 5. There must 
be a KEYn parameter for each key in the file. s specifies the size of the key and 
may range from 1 to 80 bytes. | specifies the number of bytes preceding the key. If 
| is omitted, O is assumed for fixed records and 4 for variable records. DUP 
specifies that duplicate keys are allowed. NDUP specifies that they are not allowed 
and is the default case. CHG specifies that the key can change during update. 
NCHG specifies that it cannot change and is the default case. 


KEYn parameters are required unless you intend to accept the KEYn parameters 
that were specified when the file was created. If so, no KEYn sbeeiications Shou 
be present. 


For IRAM characteristic files, n > 1, s < 3, DUP, and CHG are not permitted. 


13B.5.12. Suppressing a File Lock (LOCK) . 


See 11.4.11 for a detailed explanation of the LOCK keyword parameter. 


13B.5. 13. Spectiying prodeeeing Mode for eae Files (MODE) 


MIRAM files can be processed sequentially or randomly as specified by. the MODE 
keyword parameter. 


Keyword Parameter MODE: 





Specifies ea sieulial file Brocess i: This is the default case. 


MODE= RAN 
Specifies random file processing. 


MODE=RANH 
Specifies random file processing (hold sequential position). 
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13.B.5.14. Specifying Optional Files (OPTN) 


If your program does not need to use a particular file each time you execute the program, 
the file is considered an optional file. Only sequentially pineeerae files can be ens 
files. 


Keyword Parameter OPTN: 


OPTN=YES 
Specifies that the sequentially processed file is an optional file. When this 
parameter is specified for a file not allocated to'a device’by:a DVC. job control 
statement, control is transferred to your EOFA routine when you issue an input 
operation. Control is transferred to your. ‘program inline wy no error when you 
issue an output operation. ; 


13B.5.15. Specifying Type of Operations rae! 


When you process a file you must specify the type of operations you are going to perform 
(keyed operations or. nonkeyed operations). fs nie 


Keyword Parameter PROC: 






Pepenee Rered operations. nue: is the: oki case. 


PROC= UNK - : 
Specifies henkeyed operations. 


13B.5.16..- Specifying Record Control Byte (RCB) 


When a file is created, a record control byte (RCB) is appended to the ne of each 
record unless you specify that you do not want this. 


Keyword Parameter RCB: 


RCB= -NO 

This specification only applies to files that are being created. it is required for 
IRAM characteristic files and it specifies that each record is not to:contain a 
record control byte. If this parameter is specified, delete functions will not be 
permitted when the file is subsequently processed. The default case is that each 
record will contain an RCB. When the file creation program is completed and the 
file is closed, the format label is marked to indicate whether or not the RCB is 
present. Once the file is created, this format label indication cannot be changed; 
that is, if you subsequently process the file and attempt to use the RCB 
parameter, the format label indication will override it. 
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13B.5.17. Specifying Record Format (RCFM) 
This parameter specifies the record format, either fixed-length or variable-length. 


Keyword Parameter RCFM: 








peci ies fixed-length records. This is the default case. 


RCFM=VAR.. . 7 
Specifies. variable- ieaoth records. The first four bytes of a apebles length record 
is the record descriptor word (RDW). The first two bytes of the RDW contain the 
«..effective record size that you supply on output and data management supplies on 
input. The record size includes the 4-byte RDW. Variable-length records are 
contained within a fixed-size slot that is equal to the RCSZ specification. 


13B.5.18. “Bpeenying Record Length (Resz) 
This parameter is alwave required. It ecacitiee the isngti tot sachs record in bytes. 
Keyword Parameter RCSZ: 

RCSZ=n ers 
Specifies the length of each_record in bytes. If you have Gariabie: seorde: this 


parameter should specify the maximum size plus the 4-byte record descriptor 
word (RDW) required for variable-length records. oe FAQUre oe ae 


13B.5.19. Specifying the Record Retrieval Purpose (RETR) 


If you are going to retrieve records for other than information purposes, you must use this 
parameter. 


Keyword Parameter RETR: 





Specifies that records are to be retrieved for information purposes only. This is 
the default case. 


~ RETR=MOD ; 
Specifies that pLBeeIee are to be retrieved for modification. ° 


RETR=REP. 
species that ee are to ) be retrieved for replacement. 
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13B.5.20. Specifying the Location of the Relative Disk Address for Processing a 
MIRAM File by Relative Record Numbers one! 


This paranicter is always reauired: It specifies where the relative disk address: is placed in 
your program for use in processing by relative record number. 


Keyword Parameter SKAD: 


- SKAD=symbol 
. Specifies the symbolic address in your. program dinate you place the relative disk 
address for use in processing files by relative record number. The form of the 
relative disk address is a 4-byte value. The first record is relative record 1. 


13B.5.21. Verifying Output Records (VRFY) 


You can specify that data management is to check the parity of output records after they 
have been written to disk. 


Keyword Parameter VR FY: 


VRFY=YES 
Specifies that data management is to check the parity of output records after 
they have been written to disk. If it detects bad parity, data management sets the 
parity check flag (byte 2, bit 2) in filenameC and transfers control to your error 
routine, or to your program inline if you have no error routine. If you specify this 
parameter, it will result in an increase in execution times for output operations. 


13B.5.22. Specifying File Processing with One Volume Colne at a Time (VMNT) 


If you want to process a file with one volume online at a time, you must Speci”: this 
parameter. 


Keyword Parameter VMNT: 


VMNT=ONE ; 
Specifies that the file is to be processed with only one volume online at any time: 
A file that is created in this manner must be processed in this manner. Nonkeyed 
random operations are not permitted. If a file was not created for processing with 
one volume online at a time, it cannot be processed in this manner. 
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13B.5.23. Specifying Record. ee ee in a Work Area. pon 


You can use this parameter to sapecity that your records are to be processed i ina work area 
rather than in a data buffer veo} area. 8 


Keyword Parameter WORK: 


WORK=YES 
Specifies that input and output records will be processed in a work area‘rather 
than a data buffer area. The IORG parameter should not. be specified when the 
WORK parameter is specified. lf both are specified, the WORK parameter is used. 
When you issue input, update, output, ‘or delete operations, you specify the 
address of the work area. The WORK parameter is required for all output, keyed 
update, and delete operations. 


13B.5.24. Nonstandard Forms of the Keyword Parameters 


OS/3 data management accepts certain variant spellings for me keyword Paes 


described in this section. These variations are: 


DTFMI 0S/3 

- Spelling» Standard Form 
BFSZ —sBLKSIZE/BKSZ_ 
OFA —sC«EOFADDR-~ 
ERRO ERROR — 
INDA ——sINDAREA 
INDS INDSIZE 
IOA1 IOAREA1 
|OA2 IOAREA2 
IORG : IOREG 

KARG ——~KEYARG| 
OPTN OPTION 
RCFM RECFORM 
RCSZ RECSIZE 
SKAD SEEKADR 
VRFY VERIFY 


WORK WORKA 
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13B.6. MIRAM KEYWORD PARAMETERS — DD JOB CONTROL STATEMENT 
SUPPORT ONLY 


The following keyword parameters can be specified on/y by using a DD job control 
statement. 
13B.6.1. Variable Sector Support for MIRAM Files (VSEC) 


The detailed explanation of this facility for IRAM files (13.5.1) also applies to MIRAM files. 


13B.6.2. File Recovery Support for MIRAM Files (RECV) 

The detailed explanation of this facility for IRAM files (13.5.2) also applies to MIRAM files. 
13B.6.3. Automatic Computation of Initial Allocation Percentages for MIRAM Files 
(AUTO) . 

The detailed explanation of this facility for IRAM files (13.5.3) also applies to MIRAM files 


except that normally 0% of the initial allocation is assigned to the index partition for MIRAM 
files. 












or 
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14. Nonindexed Disk File Formats 
and Conventions 


14.1. GENERAL 


This section describes the disk file ouiats and conventions that are part of itis adaxed 
file’ processor system of OS/3 data management. The system comprises three basic 
methods for processing or accessing disk files without indexes: the sequential access 
method (SAM); the direct access method (DAM); and a combination of these two, fermed 
simply the ° ‘nonindexed method,”” which has no acronym. : vs 


‘The three methods of processing are = explained in detail, in Section 15, wee describes: 


m~~ the logical input/output control: system locs),’ or processor, that 08/3 data 


management furnishes’ you for each method, 


‘™ the imperative “macroinstructions - ‘that: constitute the actual “repertoire of tee 


processing functions available to you; and- 


# the define-the-file (DTF) declarative macros you will use to inform data management 
how your files are to be accessed and how you have eu Le 


_In both this section and Section 15, the term “‘DTF” is applied both to this type of 
declarative macro and to the file table that. each DIF sets up for data management to use 
_while you are processing ‘your file. | 


gyoie 


. You define your sequentially processed’ disk files to data management with the DTFSD 
declarative macro; consequently, these files are often called DTFSD files. Direct ‘access, ‘or 
. randomly processed, files (these terms are synonymous in this manual) are defined by the . 
-DTFDA declarative macro and are termed DTFDA files. Files that you want to process by a 


combination of both sequential and random techniques you will define to data 
management with the DTFNI declarative macro. You may subdivide your DTFNI files into 


-aS many as seven file partitions; you define certain details’ of each Partition with yet a 
fourth Nps of mae declarative: macro: . the DPCA macro. — 
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_To summarize: 
m Three access methods: 
" ‘Sequential’ access ; method 1 (SAM) 
Direct access aetna (DAM) 
Nonindexed access method (a combination of SAM and DAM techniques) 
# Four define-the-file (DTF) declarative macros: 
DTFSD — defines a sequentially processed, nonindexed disk file 
DTFDA — defines a randomly processed tees access), nonindexed disk file 


DTFNI — defines a nonindexed disk file that is to. be processed sequentially, randomly, 
- or by a ‘combination of both techniques os ; 


DPCA — detines-certain- particulars.af'a partition of a DTFNI file 


The various access methods and nonindexed disk file descriptions share certain ceoneupe 
of file organization, file labelling, record formats, and record addressing; these are 
described generally in this section, although some details are further developed in Section 
15. You will notice some differences from the. OS/3 indexed sequential access method 
(ISAM), described in earlier sections of this manual: chief of these, of course, is the 
_absence of any. index structure. Another difference is that ISAM does not allow you to 
have your own header and trailer labels. A third point of difference lies in the. concept of 
AEVS (14.3. 3) 


14.2. FILE ORGANIZATION 


All. DTFSD, DTFDA, and DTFNI files in. the 0S/3 nonindexed processor system may reside 
on one or more disk volumes and may be termed multivolume files. Multivolume DTFNI 
and DTFDA files must have a// volumes of the file mounted and online for processing and 
-may consist of no more than eight volumes. Multivolume DTFSD files are maintained in 
_single- -volume mode — only one of your disk packs being online at any time; there is no 
limit imposed by OS/3 on the total. number of volumes you may have in a DTFSD file. 
Data management. communicates with the operator for you, automatically, to request and 
validate mounting of the successive volumes. of a. multivolume DTFSD file. 


All. 0$/3 Sonindexed disk files. are terminated by a logical end- sats file (EOF) pointer to the 
block one after the highest block in the file in which you have placed a data record. The 
address of this block is file- or partition- relative; that is, its ‘numbering, is related to the 
address of the block that begins the file or — if you are considering a partition of a file — 
begins this partition. The significance of the logical EOF pointer lies in the actions that 
occur when the address is accessed during sequential processing of an input file. 
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In DTFSD files (which have only one volume mountéd online at a time), the EOF pointer 
also indicates the logical end-of-volume (EOV) for the online volume. When you have 
finished creating such a file and issue the CLOSE imperative macro to terminate 
processing, data management stores the address of the block next after the current block 
as the EOF/EOV pointer or end-of-data ID (EODID)-in the DTF file table and on the disk 
format 2 label for the file. No special flag or notation. is written in the data area at this 
relative disk address. When data management encounters the EOF address during input of 
your file, it transfers control to a routine you have prepared to handle the end-of-file: 
condition. (This routine, called the EOFADDR routine from the keyword parameter by 
which you specify it in your DTF, is described in: 15.6.4; see 15.7.2 for the CLOSE macro.) 
You should remember that, for multivolume DTFDA and DTFNI files (all volumes of. which 
are mounted and online at all times when you are processing), there is no EOV in the 
DTFSD sense and no need for an EOFADDR routine except for input DTFNI files you 
Races ey 


14.2.1. - Partitioning DTFNI Files 


You may subdivide each DTFNI file into as many as seven file partitions, each with its own 
partition name, record size, block size, and other characteristics. You define the overall file 
characteristics, name all the: file. partitions, and describe. the first. partition in the DTFNI. 
declarative macro; you then use separate DPCA declarative macros for each partition to 
define the characteristics of-the partition. Every DTF file table has a-length of 242 bytes, 
but the table established by the DPCA declarative macro is only 82 bytes long; it is termed 


the partition control appendage. You access a file partition for processing by name, using 
the SETP macro (15.7.4). 


14.2. 2. »Subfiles: in DTFNI Partitions | ee. a 

You: may. tienen subdivide: eden pantiian aie a DTENI file into as many as 71 daria Sipiles: A 
which you must create: in sequence. (They need not be‘ processed: sequentially, and you 
may, access, them-for processing in any. order, once you have created them.) Unlike-a file 
partition, which may. differ.in certain: characteristics from the basic: DTFNI. file, a subfile 
must not differ from the partition in any respect. Another difference between a subfile: 
and a partition is that a subfile has no name; you address one by using its partition- 
relative serial number :as;an operand of the SETS.macro by. which you access your subfiles: 
(the SETS macro is described in 15.7:5). To help it keep abreast of your.processing. of : 
subfiles, data management maintains.’subfile. tables;. it. reserves one track of the -first: 
volume: of a file:,for these when you. so instruct it by specifying the SUBFILE keyword: 
parameter in your:.DTFNI or. DPCA declarative:macro (15.6:26). Figure 14—1 depicts the 
organization of a DTFNI file into partitions and subfiles. 


sep Ae 
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Characteristics defined by DTFNI 
declarative macro instruction 





Chiaraiteristics: defined by DPCA declarative macro instructions; 
~~ ‘selected’ BY SETP imperative macro 


Characteristics defined by 
DTFNI wr. sence Po ; 5; cat ® ; : 
declarative eae: ache = ase FILE 





macro - FILE ee . File: © Oe ~ PARTITION-n — 
instruction; © «x PARTITION-1 — PARTITION-2 ear "(maximum of . 
selected by ; ‘ : a .7 partitions) 
SETP imperative * ; oar poe 
macro 
SUBFILE 
SUBFILE SUBFILE SUBFILE n 
Characteristics are 1 1 2 (maximum 
those of parent a te wh Dae ae of 71) 


Partition. Supported 
via SUBFILE keyword 
parameter inDTFNI = 7... i <3 = . —-—-----: 
or DPCA macros. Biber, ATS Dea : i : “4 Fone 
Accessed (after: Partition is 


selected by SETP macro} ar aa " ie /SUBFILE 
viaSETS macro. + | SUBFILE “SUBFILE | | SUBFILE SUBFILE ~ wee 
Created serially; may =” es rr Le fe sa 3B 4. .{ (maximum 


of 71) 





be accessed randomly. 
- Figure 14—1 : Organization of a DTFNI ‘Disk File into Partitions and Subfiles_ oe 


14.2.3. System Standard Labels for Nonindexed Disk Files 


In processing your DTFSD, DTFDA, and DTFNI files, data management: uses the OS/3: 


system standard labels for disk files. The system standard labels comprise the OS/3 


standard volume label (VOL1):and seven types of disk format labels, designated format 0, 


format 1, and so on, located in’a directory called the vo/ume table of contents (VTOC). Data 
management accesses these standard labels to retrieve information it needs about your 


file and to add: information on certain: nlé characteristics to them. All are ‘described in 


PE PPEV SUS D. 


For esumale data inainagement retrieves “the VOL1 label to find the: location of thie VTOC. 
Here, it will read the first record in the VTOC (the format 4 label) to obtain the address of 
the last active format 1 label and will search the VTOC up to that address to locate the 
format 1 label for the current file. It needs this format 1 label, and any format 3 labels it 


may point to, for information about the extent space and secondary allocation for the file. 


If your file is an output file, data management will rewrite the format 1 label to add to it 


some of the file characteristics you have defined in your DTF. If your file is currently an 
input file, data management retrieves and checks these characteristics. In addition, data 
management maintains a format 2 label to control file partitions and save information on 
existing and newly created files. 





smi, 
a ° 
i 
keg 
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A look at Appendix D will make the foregoing clearer when you need to go into it. For the 
moment, however, it may be more important for you to know that these actions of data 
management are. automatic and that you will rarely need to be concerned with the details. 
(Section 16 has further information on management of your disk resources.) 


14.2.4. Optional Standard User Labels 


Unlike OS/3 ISAM, which does not allow them, the nonindexed file processor system does 
support standard user header labels (UHL) and user trailer labels (UTL). These are optional, 
unblocked records, which you may process on the opening or closing of a volume with a 
routine you make available to. data management Py specifying its address in the LABADDR 
keyword parameter in your DTF (15.6.14). 


14.2.4.1. User Header Labels 


If you have UHL, data management writes these on the first track of each volume of a 
DTFSD file, and on the first track of the first volume of a DTFDA or DTFNI file. You may 
have no more than eight UHL, ang aes may not be blocked. This is their ne 80-byte 
format: 


Byte 
9 Label 1D 
4 
Label Data _ 
76 | 











Field Bytes Code Description 
Label ID O—3  EBCDIC Contains 4-byte label identifier: 


UHL, followed by a label number 
which ranges from 1 through 8 © 


Label Data 4—79 User option Contains 76 bytes of user-specified 
header label data _ 
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14. 2: 4. 2. User. braner panels. 


Data managémerits awrites. your ésiieral UTL on the first fracle of: ani volume of a DTFSD 
file and on the first track of the first volume DTFDA or DTFNI files; your UTL follow your 
UHL. You may have no more than eight, and they may not be blocked. This is their 80-byte 


form: 


ah Byte eae | 
0 : ay, Be Bt ass Label 1D 
4 
Label Data 





6. 


Field a“ Bytes _ . Code | Description : 








Label ID O—3 ~~ EBCDIC Contains 4-byte label identifier: 
c . | _ UTL, followed by a label number which | 
ranges from 1 through 8 
Label Data . 4—79....User option. Contains 76 bytes of user-specified 
trailer label data 
14.3. NONINDEXED FILE RECORD FORMATS 
The ‘nonindexed processor system handles four record formats: ~ - 
m §Fixed-length, blocked 
= = Fixed-length, unblocked _ 
= Variable-length, blocked 
a Variable- ‘length, unblocked, 
DTFSD and DTFNI files may comprise records in any of these four formats, but DTFDA files 


may not be specified as having blocked records (that is, physical blocks containing more 
than one logical data record, fixed- or variable-length). 


err 
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It might be well at this point to review three OS/3 definitions: 


block 
The portion of a file transferred into or out of main storage by a single access. 


buffer = 3 o m3 
An area in main storage for handling a block of data. Must not be smaller than 
the blocks to be handled. 


record 
The collection of contiguous characters, designated as such to data management 
by the user, for handling as a unit. Record size must not exceed block size. 


The system does not handle undefined records; if you.do not specify the record format in 
your DTF, data management assumes that your records are fixed and unblocked (that is, 
you have oniy one fixed-length logical record in each physical block). No record may 
occupy more than one block, nor may any record or block span from one disk track to 
another. 


14.3.1. Fixed-Length Records 


Fixed-length logical records are all of equal length for a given file or partition. When you 
specify that your fixed-length records are unblocked (or leave this specification to data 
management's default assumption, just mentioned), you do not need to specify the 
RECSIZE keyword parameter because data management takes the number of bytes per 
records as being what you specified with the BLKSIZE keyword. However, when you block 
your fixed-length records, you must specify both the BLKSIZE and RECSIZE keywords, and 
the value of BLKSIZE must be an exact multiple of RECSIZE. 


When you are using the-variable-sector SPERRY UNIVAC 8411, 8414, 8424, 8425, 8430, 
or 8433 Disk Subsystems, your BLKSIZE specification governs exactly the number of 
bytes of data read or written. On the other hand, if you are using the fixed-sector SPERRY 
UNIVAC 8415, 8416, or 8418 Disk Subsystem’ and do not specify a blocksize that is a 
multiple of 256 bytes, the block written will always be larger than the specified block size; 
this is because the system writes or reads only in multiples of 256 bytes-to the 8416 disk. 
Your BLKSIZE specification controls the number of bytes treated as data within a logical 
block, which is a multiple of 256. (For example, if you specify BLKSIZE=400 for a file that 
is to reside on an 8416 disk, data management will write out a block of 512:bytes.).You 
must be sure to reserve adequate buffer space for a8 ‘circumstance, “because a: oe route 
block: will be read into. ‘the buffer during potelovalin ze 


Figure 142 illustrates the two fixed- iewaihe caer ‘oninets: and their sslalionehins to tine 
I/O area and DTF keyword parameters. 
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FIXED-LENGTH, UNBLOCKED RECORD 


logical record 





FIXED-LENGTH, BLOCKED RECORDS 7 


logical record, : logical record, logical record,, logical record, 





LEGEND: 


D Length of data | in each logical record; you specify this length only when your records are blocked, using the RECSIZE 
keyword parameter in your DTF macro. 


i Length of 1/0 area; you. always specify this with the BLKSIZE keyword parameter of your DTF macro instruction. If 
your file is to reside onan 8416. disc, | must be a multiple. of 256 bytes, and therefore the length of the block. ‘may | 
exceed the nearest multiple of fixed-record length. 


NOTE: 
In preparing the illustration of blocked records, the arbitrary choice was made to show four logical records per physical block. The 


- actual number you choose is a matter of file design. Remember that blocking is. not specifiable for DTFDA files. 


Figure as prone Physical Record Formats, Nonindexed Disk Files without Keys . 


14. 3. 2. “Variable- Length Records 


When your: jebere are variable- length, 0S/3 data manaoement preempts the first four 
bytes of every block for use as. a block descriptor word.(BDW). Data’ management 
calculates the effective length of the block and inserts this for you.into the first two bytes 
of the BDW; it reserves the last two bytes of the BDW for its own use. You need not be 


concerned with the BDW, therefore, other than to allow for the fact that it ESaures by sour 


bytes the block space“available for your logical records. . 


You are concerned, however, with the first four bytes of every logical record; these are 
also needed by data management for control and constitute the record descriptor word 
(RDW). 


Data management, again, reserves the final two bytes of the RDW for its own use, but the 
first two bytes must contain the length of the record of which the RDW is a part. Before 
submitting a new record to be blocked, you must place the proper binary value in this 2- 
byte field. 


oo, 
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( : When you specify that your records are variable and unblocked, data management will 

es write out one block for each logical record you submit, regardless of the amount of 
available space remaining in the I/O area. If you have specified blocked ‘records, data 
management will pack as many complete records as possible into each block before 
writing it. In either case, the length of the block it writes will. be the number of bytes you 
have specified with the BLKSIZE keyword parameter, unless more must be written 
because of roundup for the 8416 disk. : 


Unless your logical records follow some anusual pattern, there will always be varying 
amounts of unused space at block ends. 


You must not use the RECSIZE keyword parameter in your. DTF for a file containing 
variable-length records because data management expects to find the record size in the 
first two bytes of the RDW. 


Figure 14—3 illustrates the layout of both formats for variable records and relates these to 
the length of the !/O area. : 


VARIABLE-LENGTH, UNBLOCKED RECORD 


logical record 


si me, 
non, 


Neo 





VARIABLE-LENGTH, BLOCKED RECORDS 


logical record, 





LEGEND: 


B Block descriptor word, four bytes. Vou Must reserve space. for this in your, 10 area; it is also part of the Block on 
disc. Data management calculates the block length i in bytes and writes this i in ‘the first two bytes of the BDW; the last 
oo two bytes are reserved. 


R Record descriptor word, always first four bytes of each variable-length record. You determine the length of each 
logical record in bytes, including this 4-byte RDW, and place it in the first two bytes of the RDW. The last two 
4 bytes are reserved, ae 


"isco 


Figure 14—3.. Variable-Length Physical Record Formats, Nonindexed Disk Files. without Keys. (Part 1. of 2) 
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v! LEGEND (cont):: ° 
Doo os ae of the data portion of your record. 


v. ; Length, of he Saaible record (measured in bytes); includes four bytes for the RDW. You insert this number into the 
first two aby ieee of the RDW, in binary form. 


| Length of the physical block, both on disc and in the I/O area. The I/O area length you specify via the BLKSIZE keyword 
parameter must accommodate the largest variable-length block in your file. 


Unused space 


Supplied by data management 





NOTE: 


‘In ‘preparing this illustration of blocked records, an arbitrary choice was made to show two logical records per physical block. 
The actual number you choose is a matter of file design. Remember that you may not specify blocked record format for 
DTFDA files. This does not mean that OS/3 DAM does not handle the block format in which the unblocked variable-length 
record is shown here and actually exists on disc. It does. The point is that DAM does not block or deblock records for you. If 
what you can only describe to DAM via the DTFDA macro as an unblocked record is actually a block of logical records, you 
must provide for blocking and deblocking them yourself. 


You will probably find the DTFNI file the better alternative; for one thing, the PUT and GET imperative macros may 
be issued to a DTFNI file for record level access; but they cannot be issued to a DTFDA file. In random processing 
of a DTFNI input file containing fixed, blocked records, data management provides you with the displacement of the 
desired record in the block, loading this into filenameD after the READ/WAITF macro sequence. 


%y 


Figure 14—3. Variable-Length Physical Record Formats, Nonindexed Disk Files without Keys (Part 2 of 2) 


14.3.3. Optional Key Fields with Nonindexed Files 


Up to this point, our discussion of record formats has ignored an optional oe you may 
want to include in the design of your DTFDA and DTFNI files: a leading key to identify each 
physical block. 


A key in the nonindexed file processor system is simply a character string, unrelated to the 
disk location of a physical block, which you specify and write with the block to uniquely 
distinguish that block from all others in the area of search. Search can be confined to a 
single track or-can run from starting point to end of cylinder. Key length has:certain limits, 
but key content is almost entirely up to you. The only restriction is that_no byte of any key 
may contain the hexadecimal value FF. This value may produce erratic results during 
keyed retrieval. Otherwise, keys to your files may be constructed according to any scheme 
meaningful in the context of your file-processing needs, although uniqueness within the 
search area is assumed to be necessary because you will search for one specific block in 
the area, seeking ‘to identify it by its key alone. Keys may be used with DTFDA and DTFNI 
files, and partitions’of DTFNI files; they are not used with DTFSD files.* 


*OS/3 data management does not provide you with a means for using keys in processing your DTFSD files because, in Naa 
sequentially constructed files like these, each block is already uniquely. identified by its relative location. OS/3 assumes that 
your reasons for organizing the file for sequential access only do not include a need to identify a block by some other means. 


en, 
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If you are familiar with OS/3 ISAM, you might note at this’ point that;.in the nonindexed 
file processor system, you associate a key only with a physical b/ock, whereas in ISAM 
each of your logical records may have a key. 


Sequential processing does not necessarily preclude the presence of keys. A DTFNI file or 
partition, for example, which you may-.always - process sequentially, may have a key 
associated with each block of data. If it does, moreover, you must take the key into 
account when you jissue the sequential access PUT and GET imperative | macros to putes 
the file. (This point is developed further in 15.7:9.5.) 


A point to note here, perhaps, is that processing a file with the OS/3 sort/merge program 
is quite different from sequential processing in the data management sense. With 
sort/merge, you are concerned only with sequential organization of files and use the term 


_ key in a very different sense: a record may contain a number of fields, located anywhere 


within it, which sort/merge uses to resequence the file. Each of these fields is considered 
a sorting key; these may overlap and need not be unique. In the ‘data management 
nonindexed system, however, keys are used only in direct access files. and. only with 
blocks; each block has only one key, always unique, and always — located in front of the 
block, = 


You have noted that the length of the key has certain limits in the nonindexed processor 
system: the minimum key length is 3 bytes, and the maximum is 255 bytes. Another point 
to remember is that all keys in any one file must have the same length; the only exception 
to this rule is the partitioned DTFNI file, in which each partition may have its own unique 
key length, uniform throughout the partition. You may not include blocks without Keve ina 
file of keyed blocks. oops 


When you are srodessing blocks: with keys, you inform data management of the actual key 
length it will find or place with your blocks on disk by specifying the KEYLEN sore 
parameter in the DTFDA, OTFNI, or DPCA declarative | macro. 


The various forms aes READ and GURUE Senperatieeonineres are designed to give you a 
useful set of options for retrieving records by key and writing or updating the key and data 
portions; these are described in Section 15. 


The effects of keys on the physical block length and, consequently, on the layout of your 
blocks on disk and in the 70 buffer are illustrated in Figure 14—4 for both fixed and 


- variable rovords: 
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FIXED-LENGTH, UNBLOCKED: RECORD 


_key field logical record 


logical record, 


logical record 





VARIABLE-LENGTH, BLOCKED RECORDS 


key field pom fom logical record 1 
a ee ee eee D R — > OO —— 
So - Vv 


Figure 14—4. Keyed Fixed- and Variable-Length Physical Record Formats, Nonindexed Disk Files (Part 1 of 2) 
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LEGEND: 

K Key field, supplied by you. Minimum 3 bytes, maximum 255, All keys in same partition or file must have same 
length. Notice that only a block has a key; individual records within a block do not. 

B Block descriptor word, always four bytes. You reserve space for this at the head of the block, after the keyfield; data 


management calculates and inserts block length into first two bytes. Last two bytes are reserved. 
R Record descriptor word, always the first four bytes of your variable-length record. You determine the length of each 
logical record in bytes, including this 4-byte RDW, and place it in the first two bytes of the RDW. The last two 


bytes are reserved. 


Length of the data portion of your logical record; varies for variable-length records. Always the same for each fixed- 
length record throughout file. 


Length of a variable record; includes four bytes for the RDW. You insert this number (measured in bytes) into the 
first two bytes of the RDW, in binary form. 


Length of the physical block, both on disc and in your I/O area. The I/O area length you specify via the BLKSIZE 
keyword parameter must accommodate the largest physical block in a file of variable-length records. 


D 

V 

I 
WN Unused space, if any 
S 


Supplied by data management 


Tey, 


= In preparing these illustrations of blocked records, an arbitrary choice was made to show two logical records per physical 
block, in both the fixed- and variable-length formats. The actual number you choose is a matter of file design. You may not 
specify that records are blocked for DTFDA files. 


Figure 14—4. Keyed Fixed- and Variable-Length Physical Record Formats, Nonindexed Disk Files (Part 2 of 2) 
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15. Nonindexed File Access Methods: 
Function and Operation 


7 


15.1. GENERAL 


This section describes the nonindexed file processor system used with OS/3 data 
management. The. nonindexed file processor system is a generalized input/output control 
system (lIOCS) that enables you to create and maintain data files on all disk subsystems 
supported by.OS/3 and to process these files in a sequential order, a random order, or by 
a combination of both sequential and random file processing techniques. It offers standard 
techniques for processing sequential.access method (SAM) files and direct access method 
(DAM) files, as well as enhanced Gapaunities for processing pOuInGEXeS files ea a 
combination: of beth menOe ii adt 2 4 oR : 


The: aonindexed processor. system: operates on disk files that you dsssb to 0S/3 data 
manegement sees DTF tact. we file) Bsclarative macroinstruetions: 


a SAM files are aerindd by — DTESD declacaiive macro; 
m DAM. files by the DTFDA Gociatauve: macro; and 
. | nonindexed files through the DTENI macro. 


You arovids descriptive jatormiation to ‘the declarative macros by speciying? the Keyword 
parameters associated with each. From these, data” management builds the epee mars 
DTF file table for the type of file you have selected. ee 


You perform I/O operations upon your file by issuing imperative macroinstructions in your 
basic assembly language (BAL) program. These, providing the essential interface between 
your program and OS/3 data management, are what you use to access and generate data 
within your file and to position it for more effective processing. Data management 
communicates directly with the resident. systems access technique (SAT) of the 0S/3 
supervisor for access to the physical. np oHtpae a Lovee Ge): . 
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The transient routines invoked by the OPEN macro, for example, complete setting up your 
DTF file definition tables and perform certain checks to ensure the integrity of your 
definition. Once you have opened a file, you may then access it via the imperative 
processing macros (GET,..PUT, CNTRL, READ, WRITE, etc). You terminate your file 
processing by issuing a CLOSE macro and Gan then do no further processing on the data 
in the file until you reopen it by issuing another OPEN ‘macro. 


When you are processing files sequentially, the GET macro reads data blocks and delivers 
individual records to you, one at a time. You output records to the disk file with the PUT 
macro, which you may also use to update records. Data management provides buffering 
via blocked records and automatically blocks and deblocks them for you. You may overlap 
your |/O with your sequential processing by specifying a work area, or a second |/O area, 
in addition to the one I/O area that is always required for each file. As is true ecorengneut 
OS/3 data management, your |/O areas must be half-word aligned. a 


For randomly processing files, data management offers you the capability to erase data 
from an expired or newly allocated file, to.create blocks in.a-file, or to expand a file by 
generating data blocks in space newly allocated to it: You retrieve records via the READ 
macro and output them via the WRITE -macro; each ‘of these macros has several forms, 
which you specify as required, to access a block by its relative’ a ecdiess: or by a key to 
be matched via Beare) and an gaetess for starting the Searels 


You may » mibaivide each fonindexed file, detined by the DTFNI declarative macro, into as 
many as seven file partitions, each having its own I/O area and characteristic block size, 
record size, and key length. Each partition of a DTFNI file may be further subdivided into as 
many as 71 serial subfiles. You. may gain access to the specific partition and subfile 
required by issuing special imperate macros (SETP, SETS, ner camer) provieed for this 
purpose. as < : iy cs : : 


For all three file types, OS/3 data management gives you the option of generating: and 
processing your own standard user header and trailer labels. You may accompish this by 


coding a special user label processing routine; which receives control from the OPEN and 


CLOSE transients. You should remember that user standard labels are associated with 
your fife and are not maintained at, the partition or subfile level. Your label processing 
routine, furthermore, may not issue any of the file processing MnIperave macros, abeudn 
a special macro, LBRET, is available for use in this routine. 


It is important for you to keep. in mind, as you study this section, that differences exist 
between OS/3 data management and the data management of SPERRY UNIVAC or other 


systems you may be acquainted with. Another point to remember is that some macros are: 
used for other types of OS/3 data management files than those described in this section, 


with slight differences..in format or effect. For.example, the imperative macro SETF (15.7.8) 
is also used for magnetic tape files defined by the DTFMT declarative macro, but in its tape 
application has no UPDATE positional parameter. 


eos 


a 
4a 


al 
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Following functional descriptions of each of the three file processing methods, this section 
of the manual presents a discussion of the DTF declarative macros. .A summary of the 37 


keyword parameters (Table. 15—7) and a description of their. use follow these. The next 


paragraphs present a summary of the 18 imperative macros used in processing your files, 
and a detailed description of the use of each follows the summary. The final paragraphs of 
this. section discuss the error and exception handling features of the nonindexed file 
processor system. You. will find numerous coding examples throughout. - 


15.2. FUNCTION DESCRIPTION, OS/3 SAM 


As you have just noted, you use the DTFSD declarative macro to define disk files that data 
management is to process as sequential access files. During your processing of DTFSD 
files, you should keep in mind that multivolume DTFSD files are maintained in single- 
volume-mounted mode, only the current, volume being online at any-one time. Data 
management takes care of communicating with the operator to request and validate the 
mounting of subsequent DTFSD volumes automatically. Files defined as sequential access 
by the DTFSD declarative macro may contain fixed- or variable-length records, blocked or 
unblocked. 


For input operations, you use the GET macro; data management reads the input data and, 
deblocking it automatically if required, delivers the records, one at a time, to you: For 
output, you deliver records to data management one at a time via:the PUT macro; when a 
full block of records is ready, data management writes it to disk. You may process input or 
output records in a work area or euseyy in the |/O area. 


If you use a Work area, ‘dete anaceinent moves an. output: record from ttie work area to 
the I/O area; it moves an input record from the I/O area to the work area: If your records 
are blocked, or if you provide two I/O areas without:a work area, you must. supply an 
index - register (via the IOREG keyword.,. parameter of your DTF), ‘into which data 
management places the starting address of the current record position in the I/O area. 


You may overlap your.!/O operations with your other processing if you provide one or 
more work areas or a second I/O area in addition to the one I/O area you must eMave 
provide. , . 


When you are processing variable-length, blocked records in the output mode and do not 
provide a work area, you must yourself test whether the next record will fit in the space 
remaining in the current output area. When it does not, you issue a TRUNC imperative 


macro to output a truncated block to disk. Data management provides you with the. 


number of bytes remaining in the I/O area in a register that you specify via the VARBLD 
keyword parameter of your DTFSD declarative macro. 


When you are processing aput corde from, a DTFSD file, you may reach a caine where 


you want to omit processing the records remaining in the current. block or volume and. 


begin with. the first. record of the next. You may accomplish either of these actions by 


issuing the RELSE imperative macro for skipping the remaining records in the current. 


block, or the FEOV macro for skipping the remainder of the current volume. : 


~<fmn 
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When necessary, you may use:the PUT imperative macro to update: records you have 
retrieved, but you may not change their record length. You issue the PUT. macro for the 
record to be updates tolowing the GET macro by which it is retrieved. mee 


In addition: you may aond a DTFSD file Jpevend the current ‘end: bigs -file (EOF) address of 
the last volume of the file. There are two ways of doing this: in the update mode, you 
provide for this extension by coding it in your EOF routine; for output files, you specify the 
extend mode of processing in the LFD job control statement of the device assignment set 
by which you allocate the file. (The details of these two methods are Geveroree under the 
discussion of the PUT macro; see 15.7.9.2 and 15.7.9.3.) 


To use a DTFSD file as a disk work file, creating and then processing it under the same 


DTF file descriptor, you initially specify TYPEFLE=INOUT in the DTF, open the file for 


output and create it, and then close it. Changing the file processing direction to input via 
the SETF imperative macro, you then reopen the file, Using the same DTF, to retrieve and, 


optionally, update your records. The details of this method are developed under the 


discussions of the oe macro (15. 7. 8) and the PUT macro (15. 7. 9. 1). 


15. 3. Rona DESC Na OS/3 besfiie 


You dating DAM. files: which? you process at random with OS/3 data management, by 
means of the psi BeCetatie macro. 


Aasther way in whieh OS/3 DAM. differs from 0s/3 SAM and OS/3 honindexed. file 
access method is that DAM supports fixed- and variable-length records in unblocked 
format only, whereas the other two also support blocked records. Consequently, you have 


no need of a work area or a second I/O area, as you do for processing sequential blocked: 
records or for overlapping |/O with processing, and therefore the DTFDA declarative macro. 


does: not have lOAREA2, IOREG, RECSIZE, nor “WORKA keyword porametere: ee sociated 
with it. 


A third point of difference to remember between SAM and DAM is that all volumes of a 
multivolume DAM file are kept online when you are processing; there is no EOF concept 
in the SAM sense and consequently no EOFADDR keyword parameter associable with the 
DTFDA declarative macro, nor is there a combined input/output file type 
(TYPEFLE=INOUT), or need’for an UPDATE keyword parameter. By 


OS/3 DAM provides you with a means:for creating records in a file, erasing data from an 


old or newly allocated file, and expanding a “file by satire tecords in Space ney 
allocated to it. a , 


The input work horse for direct access files is the block-level READ imperative macro, 
which has two forms (READ,KEY and READ,ID) for accessing a block through a search on 


key (starting the search at an address you specify) and for accessing a block directly ata 
relative disk address (ID) that you provide to data management. You indicate to data 
management which of these forms of the READ macro you intend to use by specifying the’ 
READKEY and READID keyword parametes in your DTFDA declarative, and you provide | 


ee 
eo, 
‘ 
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data management with READ-related. information in a number..of other DTF ‘keyword 
parameters, discussed:in 15.7.14. To give data management time to locate the block. you 
want and to move it to the |/O area, you must issue a WAITF imperative: macro after every 
‘READ macro issued to.a DTFDA file; before you:may issue another. imperative to the file. 
This ‘assures you that the data. transfer has taken Pe as Specntee before you ieee 
further. 415.7:16), - Ser 7 


Another imperative macro for. DTFDA files that must. be Seed with a fellewinig WAITE 
macro —-and for the same reasons — is the direct access output processing. macro, 
WRITE, which, like READ, is also a block-level macro. The WRITE-macro has five forms 
that may be used with each other and with the two READ macro forms to create, update, 
and: erase. direct .access disk files. Two of.. these forms -(WRITE,RZERO and 
.WRITE,AFTER,EOF) do not actually output a block. to disk. You-use these to reposition the 
‘disk: access arm to a-new-track, or to record the ID returned after the last block was 
written as the end of-data in the file. These forms of the WRITE command, and the WRITE- 
related: DTFDA keyword parameters, are’ developed in detail in’ 15:7.11 and 15.6... — 


15.4. FUNCTIONS OF THE OS/3 NONINDEXED FILE ACCESS METHOD 


~The logical IOCS processor, which processes. nonindexed ‘files you define with the DTFNI 
‘declarative macro, will also process. sequential files defined by the DTFSD-macro and 
direct. access files you define with the DTFDA macro. It supports all OS/3 random access 
“file processing imperative. macros and all the sequential processing macros; however, only 
files you define by the D7FN/ macro may be processed by the combination of both direct 
“and sequential processing techniques. Similarly, it is. important to remember that only to 
'DIFNI files may you issue the following five: uepetee macros: NOTE, oo POMS: 

SETP, and SETS. ee a woe 


~The DTFNI declarative macro has a number of unique keyword parameters: you will specify 
to realize other extensions to file processing techniques which apply. :to nonindexed disc 
files. under OS/3. data). management: the: PCA and SUBFILE keyword parameters,. for 
example, by which you specify that your DTFNI file is subdivided into file partitions and 
that these, in turn, are subdivided into partition subfiles. You will note also the SIZE and 
UOS (unit of .store) keyword. parameters, which: you use for ey nauuc allocation and 
extension: oF DTFNI PANES tothe iedbateeds level. 


“You may sdtanide: a DTENI file into aS many as seven file partitions, each of which has’ its 
own I/O area or areas and its own characteristic record size, block size, and record format. 
Each partition you:may further subdivide:into a -maximum of 71 subfiles, having the same 
characteristics as the partition of which’ it is a part. You define. a DTFNI file as being 
partitioned by specifying two or more PCA keyword parameters in the DTF and by coding a 

' DPCA (define partition contro! appendage) declarative macro for the second through the 

»seventh partitions of the file. In the DPCA declaratives, you specify a keyword parameter 
‘for each aspect in:which the partition differs from the parent DTFNI file; for this reason, 

-you do not prepare a separate Se Geetription for the first paninon — it | is 3 already fully 
described: mn the renee macro.* = ; ae 


*/t is not mandatory, of course, that each partition of a DTFNI file have different record lengths or formats; however, even 
though a partition may be the same as the parent DTFWNI/ file in all other respects, if it is a partition it has its own separate 
name, blocksize, and 1/O area and requires its own DPCA declarative macro for separate identity and accessibility. 
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When you open the DTFNI file for processing, only the first partition is set active and 
available to you. for processing; to gain access to some other partition, you issue the SETP 
imperative macro to the file and specify the partition you want to process by name. 
‘Subsequent processing is carried out on this partition until. you select another by issuing 
-another SETP macro. When you have selected the partition you want to process, you issue 
a SETS imperative macro to specify whichever subfile it is you want to process, having 
previously indicated that data management is to support subfiles for this file via the DTFNI 
or DPCA keyword parameter SUBFILE. These procedures are detailed further in the 
descriptions of the DTFNI and DPCA declaratives (15.5.3 and 15. 2 a and He SETP and 
SETS imperative macros (15.7.4 and 15.7. Daa 


08/3 data janagement will allocate and extend DTFNI space sutbeaatbally for you, as 
you need it, using the disk space management routines of the OS/3 supervisor and taking 
its cues from both your job-control statements and your DTFNI/DPCA keyword parameters. 
It satisfies the space requirement for the first partition from the first available area of the 
extents you specified in the device assignment set of job control statements by which you 
initially allocate the file; to the first partition it allocates that percent of the total file 
allocation you have species in the SIZE fake bos parameter of me DTFNI declarative 
macro. | ’ 


You use the UOS keyword parameter to indiate the percentage’ of additional space data 
management will dynamically: allocate to this partition, should you ever issue a WRITE or 
PUT output imperative macro referencing a block or record that lies beyond-the current 
maximum relative block address for the partition. The UOS keyword parameter specifies 
the percentage of the secondary allocation data management may assign. (You will have 
specified the total number of tracks or cylinders by which the file may be extended 
dynamically in the third positional parameter of the EXT job control statement in your 
device assignment set for the file.) 


Further details on dynamicextension are given in descriptions of the SIZE and UOS 
keyword parameters (15.6.24 and 15.6.29); each DPCA declarative macro has its unique 
SIZE and UOS keyword parameters. You should also remember that DTFNI files will not be 
dynamically extended beyond the volumes on which they initially reside. 


~ Should you ever want to re a growing DTFNI. file beyond the svsical velnie you 
originally allocated to it (assuming that these volumes are still full after your. efforts to 
reorganize the file and scratch expired or unused portions of it), you will need to copy the 
file sequentially off to tape or other disk devices, using one of the OS/3 data utility 
programs, redefine the file with a new DTFNI macro, reallocate this to new devices, and, 
copying it back, effectively create a new file. (The OS/3 data utility progres are described 
in the data utilities user guide, UP-8069 (current ey 


Other. enhancements. that apply only to processing your DTFNI files are the NOTE and 
POINT imperative macros. You use the NOTE’ macro to access the partition-relative 
address of the current record or block, which data management places in the DTFNI file 
table for you to reference. You may then use the current address for. file positioning via 
the POINT macro, which updates the current record address in the DTF as you direct; your 
subsequent file processing proceeds from this updated address. (Further details are 
developed on the NOTE and POINT macros in 15.7.17 and 15.7.18.) 


ES 


ecw 
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The imperative macro POINTS is useful to you for initializing the relative block address of 
the current partition; you select the current partition, as previously described, with the 
SETP macro. (The POINTS macro is fully described in 15.7.6.) 


15.5. NONINDEXED DISK FILE DECLARATIVE MACROS 


You will use the four DTF declarative macros described in the following paragraphs to 
define disk files and partitions to OS/3 data management. Note that, although the DTF 
keyword parameters listed in the following statement formats are presented in alphabetic 
order, you may code these in any convenient order, just so you separate them with 
commas. 


Following the statement formats are tables summarizing the required and optional 
keyword parameters; the detailed descriptions of the keyword parameters are presented in 
15.6 and a table recapitulating all of them follows the descriptions. Except for the LACE 
keyword (15.6.8) and the LOCK keyword (15.6.36), the keywords are described in 
alphabetic order. 


Refer to the Preface of this manual to review OS/3 statement conventions, and to 1.6 for 
a general discussion of DTF macros and BAL rules for coding their operands. 


In the declarative macroinstruction format delineations that follow, a comma is shown 
preceding each keyword parameter except the first, to remind you that all keywords coded 
in a string must be separated by commas. However, a comma must not be coded in 
column 16 of a continuation line, nor follow the last keyword in the string. Refer to the 
coding examples that follow. 
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15.5.1. Defining a Sequential Disk File (DTFSD) 


Function: 


You will use the DTFSD declarative macro instruction to define input and output disk 
files that you intend to process sequentially. The DTFSD macro establishes a 242-byte 
file table. Table 15—1 summarizes the DTFSD keyword parameters. These are 
described in detail in 15.6. A coding example follows Table 15—1. 


Format: 
LABEL AOPERATIONA OPERAND 
filename DTFSD 7 ACCESS=.( EXC \ 
EXCR 
) SRDO 


SRD | a 
BLKSIZE=n | 


,EOFADDR=symbol © 


i ERROPT= { IGNORE \ | 
SKIP 


[,ERROR=symbol] 
,OAREA1=symbol 

[ JOAREA2=symbol] 
[ JOREG=(r)] 
[,_LABADDR=symbol] 
[,LACE=n] 
[,LOCK=NO] 
[,OPTION=YES] 


,RECFORM= ( FIXBLK 





VARBLK 
VARUNB 


[,RECSIZE=n] 


[ SAVAREA=symbol] 
[,TRLBL=YES] 


(continued) 
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LABEL A OPERATION A OPERAND 
DTFSD (cont) ae INOUT 
,TYPEFLE= ¢ INPUT 
OUTPUT 
[ UPDATE=YES] 
LWARBLD=(r)] 
[ VERIFY=YES] 
LWORKA=YES] 





: Table 15—1. Summary of Keyword Parameters for DTFSD Macro Instruction (Part 1 of 2) 


Keyword 


Request exclusive use of file for 
associated DTF 






Specification 





















Request exclusive use of file for 
associated DTF while permitting read 
use for other jobs 


Request read function for file 
associated with DTF while permitting 
read/write for other jobs 


Request read function for both files 
associated with DTF as well as other 
jobs. No writing permitted. 


The maximum block size, in bytes 


Identifies EOF routine 
— parity error 


Address of user’s unrecoverable 
error routine 


-Address of 1/O area 
Address of alternate |/O area 


Required if records are processed in the 
1/O area and records are blocked 





EOFADDR symbolic label 


ERROPT IGNORE 


ERROR symbolic label 


IOAREA1 symbolic label 
IOAREA2 symbolic label 


tOREG (r)=general register 


LABADDR symbolic label of user's Required if user header or trailer labels 
label routine are to be created 
Required if user header or trailer labels 
are to be retrieved 
“ al 


mee ee ee | oes aed aih = = = | 















x 














Specifies factor for record 
interlace 







Specifies that file lock is not to be set 
on a lockable file at OPEN, permitting 
* read-only access 
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Table 15-1. Summary of Keyword Parameters for DTFSD Macro Instruction (Part 2 of 2) 


Keyword Specification 












RECFORM* 





FIXBLK For fixed-length, blocked records 





| For fixed-length, unblocked records; 
assumed 






VARBLK Y For variable-length, blocked records 
VARUNB cae aa For variable-length, unblocked records 


RECSIZE* n=number of bytes in For fixed-length, blocked records 
record 
ee | eee label Specifies address of save area for 
contents of general registers 
TRLBL Read or write user trailer labels when 
CLOSE issued to file. (Specify LABADDR 
also.) 


TYPEFLE INOUT For 1/0 files 


Ensen ae For input files; assumed 
oon ee 


— Lime 
VARBLD x 






















Required if records are to be written 
back to the same focation from which 
they were read 





(r}=general register x Required for variable-length, blocked 
records built in output area; register 


contains number of bytes left in output area. 


Check parity after records have been written. 








LEGEND: 

R Required Assumed parameter, if none specified 

x Optional Parameter may be changed on DD job control statement. 
ry: One option required 


Example: 


LABEL BeEennTONe OPERAND 
16 72 80 


1 
pra] pens K ai ome 


iA} = READ “ 


ESE ADDR= FINNIE 


ewes 
ite ele 7 
ee ECEORM=FIXBLK 
Reece 


oRK A= YE LL 


This example defines a file ACCNTS that is a SAM input file (by TYPEFLE default 
option). The required |/O area is designated symbolically as READ. The block size is 
800 bytes, record size is 100 bytes, and records are fixed and blocked. An end of file 
routine FINIS has been specified to handle that occurrence. No special label handling 
or error routines are provided; therefore, errors will return inline. 
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15.5.2. Defining a Direct Access Disk File (DTFDA) 


Function: 


You will use the DTFDA declarative macroinstruction to define files that are to be 
randomly processed. The DIFDA macro establishes a 242-byte file table. A summary 
of DTFDA keyword parameters is presented in Table 15—2; these are described in 
detail in 15.6. A coding example follows the table. 


Format: | 
LABEL AOPERATION A OPERAND 
filename DTFDA ACCESS= EXC 
. EXCR 
SRD 
SRDO 


[ AFTER=YES] 
BLKSIZE=n 
[,ERROR=symbol] 
[,IDLOC=symbol] 
AOAREA1=symbol 
[, KEYARG=symbol] 
[, KEYLEN=n] 
[,_LABADDR=symbol] 
[, LACE=n] 

[, LOCK=NO] 

[ READID=YES] 

[ READKEY=YES] 


-RECFORM= {ixkG \ 
VARUNB 


[ eal | : \ | 


[, SAVAREA=symbol ] 
SSEEKADR=symbol 


[| SRCHM=YES] 
[,TRLBL=YES] | 


(continued) 
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ACCESS* 


IOAREA1 symbolic label 
KEYARG symbolic label 
KEYLEN* n=key length 


LABADDR symbolic label 


LOCK 


READID 
READKEY 


RECFORM* : 
VARUNB 
RELATIVE 
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AOPERATION A OPERAND 





DTFDA (cont) Eadie {ine \] 


OUTPUT 


[,VERIFY=YES] 
L.WRITEID=YES] 
LWRITEKEY=YES] 


Table 15—2. Summary of DTFDA Keyword Parameters (Part 1 of 2) 


Specification Remarks 
ae 


Request exclusive use of file for 
associated DTF 


Request exclusive use of file for 
associated DTF while permitting read 
use for other jobs 


Request read function for file 
associated with DTF while permitting 
read/write for other jobs 





Request read function for both files 
associated with DTF as well as other 
jobs. No writing permitted. 


A capacity record on each track is assumed. 
n=maximum blocks size Length of JOAREAT1, in bytes 
Address of user error routine 


on Address of field containing the record ID 


symbolic label 


symbolic label 


Specifies that file lock is not to be set 
on a lockable file at OPEN, permitting 
read-only access. 


fo Record referenced by ID 








ots 


ot 


pon, 


“é gO, n 


er, 


ya 
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Table 15-2. Summary of DTFDA Keyword Parameters (Part 2 of 2) 


Pa [i 


SAVAREA symbolic label Specifies the address of a save area for : 
contents of general registers 

SEEKADR symbolic label Em cin | Address of wack ference field | of track | Address of wack ference field | field 

SRCHM Search multiple tracks. (If specified, file 
must be allocated on a cylinder basis.) 

i = 







User standard trailer labels are to be read 
or written when CLOSE issued to file. Specify 
LABADDR also. 














Check standard labels 






Write standard labels 


ca Records are to be check-read 
Output record is located by means of its 
relative disc address (1D). 

px | Output record is located by key. 






a 









WRITEKEY 





LEGEND: 

R Required 

x Optional 

Y One option required 


Assumed parameter, if none specified 


* Parameter may be changed on DD job control statement. 


Example (DAM Input File): 


LABEL SOPERATIONA OPERAND e COMMENTS 
10 16 


LFERMAT_ OF A DIRECT ACCESS INPUT FILE. 
, INFILE , SeOont Fz by 


Bok. Ee x 


i Ste PO nag, Eke See SP tee YN wad i oe adc ce Eee gs A aaa Pach t. Geld 


rt L ep i Pog ete. rere: dete Po 2283 4 doe ect Oe nh Poe 


DAL BLKSIzZE= 1111, 1 TNAREA TS. dia Bytes LONG 


pe asl Es Hey | Bi sad «RS Bh 


[TITDAREAI=INAREA,, INAREA IS THE INPUT/OUTPUT AREA 


eae: 1S 









| IKEYLEN=20,,, EACH, RECORD HAS A 20-BYTE KEY 
READID=YES,,, "READ, ne INFILE, ID. D. WILL. BE TssueD 


RECF OR. =FLXUNB.,, ALL RECORDS. “ARE THE SAME. STZE 





wears sat etc eS Pe ed ee eee a ha Sg, hk 
t ‘ 


DUT FI LE, prFDA BLKSI; Ze = 5 | 2512, Te 3 eae eae eae # Sees & ‘ier jae Saree Fe ies Lape Enya Soon: Minny Levee tare Se ee (Ge re i ‘ 
Hive REA Al = OUTPUT, 
PEFLE= OUTPUT, 








Soe de pe ee 


os ae Sa SO Was Wo CN Ms Te Bed Cs We OR dL Te OO 
_| MERIFY=YES>, ._ hea Sta lle ed babe me 


er cene lS. i | EET Came eee ae Fae War SN Ys ee i Pes tll 2 deci 


WRITELD= Sc reo en Pe anne Deen eT fa ff : 
E EA 2p 12 ghd 3 Se eet eee ee ek Ee ine ene Re rarer on odo 








eee E 
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15.5.3. Defining a Nonindexed Disk File (DTFNI) 


Function: 


You will use the DTFNI declarative macro instruction to define disk files that are to be 
processed sequentially, randomly, or by a combination of sequential and direct access 
processing techniques. The DTFNI macro establishes a 242-byte file table. See 15.5.4 
for a description of the DPCA declarative macro, which you use to define the second 
and all subsequent partitions of a partitioned DTFNI file. Table 15—3 summarizes the 
DTFNI and DPCA keyword parameters; coding examples follow the table. Keyword 


parameters are detailed in 15.6. 


Format: 


LABEL AOPERATION A 


filename 





OPERAND 


ACCESS= ( EXC 
EXCR 
SRD 
SRDO 
[AFTER=YES] 
,BLKSIZE=n 
[ ,ERROPT= eee \] 
SKIP 
[, EOFADDR=symbol] 
[,ERROR=symbol] 
[,1DLOC=symbol] 
jAOAREA1=symbol 
[ LOAREA2=symbol] 
[ LOREG=(r)] 
[,KEYARG=symbol] 
|, KEYLEN=n] 
[,_LABADDR=symbol] 
[,LACE=n] 
[,LOCK=NO] 
[,OPTION=YES] 
[[,PCA1=symbol] ,...,[PCA7=symbol] ] 
[,READID=YES] 
[,READKEY=YES] 
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| A OPERATION A OPERAND 
DTFNI (cont) JRECFORM= ( FIXBLK 

FIXUNB 

VARBLK 

VARUNB 


[,RECSIZE=n] 


[y /RELATIVE= { is ] | 


| [L,SAVAREA=symbol] | 
SSEEKADR=symbol 
“LSRCHM=YES] 
[, SIZE=n] 
[ SUBFILE=YES] 
|, TRLBL=YES] ; . 
»TYPEFLE= INOUT 
E: INPUT a 
OUTPUT 
[UOS=n] 
[, UPDATE= YES) 
| _L.MARBLD= (r)] 
A VERIFY=YES] . 
[ WORKA=YES] 
[,WRITEID=YES].. 
LWRITEKEY=YES] 


- 
f 
4 
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15.5.4. Defining a Partition Control Appendage (DPCA) 


When you have a DTFNI file that is to contain two or more partitions, you use a DPCA 
declarative macro to define separately the second and each of the subsequent partitions 
(that is, partitions 2 through 7). Descriptive information for the first partition (and for the 
parent file as a whole) is contained in the 242-byte DTFNI file table. The DPCA declarative 
macro sets up an auxiliary file table, ‘called a partition contro! appendage, which defines 
the aspects in which each partition differs from the first and occupies only 82 bytes of 
main storage. 


Notice that the label of each DPCA macro is partition- name; this is the symbolic label of 
the partition you have specified in the corresponding PCA keyword parameter of the parent 
DTFNI macro. 


You should also note the absence of all” Strictly file-relative keyword parameters from the 
DPCA macro: ERROPT, ERROR, and LABADDR, for example. The reason for this is to 
simplify matters for you: OS/3 data management relies upon the DTFNI file table for all 
file-relative keyword Eevee and ou do not specify these again in the DPCA macros. 


Following the format statement, ‘Table 45-3 summarizes the DTFNI and the DPCA 
keyword parameters; these are; in turn, detailed in 15. 6. Coding examples follow the table. 


Function: 


You use the DPCA macro to define the second and all subsequent partitions of a 
multipartitioned DTFNI file. A maximum of seven partitions may be defined in all. The 
DTFNI file table contains descriptive information for the first partition. Separate DPCA 
macros establish partition control appendages defining each of the others (partitions 2 
through 7). 


Format: 


LABEL A OPERATION A OPERAND 


BLKSIZE=n 
[,EOFADDR=symbol] 
jAOAREA1=symbol 

[ IOAREA2=symbol] 
[ IOREG=(r)] 

[, KEYARG=symbol] 
[, KEYLEN=n] 
[,LACE=n] 


partition-name 
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LABEL AOPERATION A OPERAND 
DPCA (cont) ,JRECFORM= ( FIXBLK 
FIXUNB 
VARBLK 
VARUNB 
[ RECSIZE=n] 
[, SIZE=n] 
[| SUBFILE=YES] 
[ UOS=n] 


L.VARBLD=(r)] 
LWORKA=YES] 





Table 15—3. Summary of DTFNI and DPCA Keyword Parameters (Part 1 of 3) 














Keyword Specification 


_ Remarks 


- al , TT 
= , + 
associated with DTF as well as other 
jobs. No writing permitted 


| suKsizes n=maximum | nemaximum block size_| size esses [LE [Te | Length of 1(OAREA1, in bytes 
Address to which control is passed when end 


EOFADDR symbolic label 
of sequentially processed file is reached 


enrort = | icone | No |v |v |v | grove paritverror 
eee ea 


a 


IOAREA1 symbolic label 








Request exclusive use ok file for 
associated DTF 


Request exclusive use of file for 
associated DTF while permitting read 
use for other jobs 









Request read function for file 
associated DTF while Permitting, 
read/write for other jobs 





Request read function for both files 










iil 
°o 
> 






Address of user error routine 














Address of field containing the record 1D 





Name of !/O area defined by user; always 
half-word aligned 


| IOAREAZ symbolic label ae Name of alternate |/O area 
IOREG (r) general register Required if records are processed in the 
1/0 area and records are blocked. 
| kevanc | | symbotctabel | label 


KEYLEN* n=key length Length of the key in bytes 


LABADDR symbolic label pote Address of user fabel-handling routine 
LACE* n=lace factor ee be Specifies the factor for record interlace 









Address of field for key used for key search 














r 
f 
‘ 
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Table 15-3. Summary of DTFNI and DPCA Keyword Parameters (Part 2 of 3) 





Keyword Specification Remarks 
LOCK Specifies that file lock is not to be set 
on a lockable file at OPEN, permitting 
read-only access 
_ epee: anne 


PCAn symbolic label 
READID 


READKEY 


eee ra Be Variable-length, blocked records 
ae 


oad Variable-length records, unblocked : 
RECSIZE* n=number of bytes 


in record x Specifies record size 


SAVAREA symbolic tee) tree eng Specifies save area for contents of general registers 
| seexanr | EKADR symbolic | symboticlabet ee ee ce Address of track reference field 


= | ine ke el 


ore fale om as 
| susFe eh ee Support division of file partitions into subfiles 


ad cee Laka Rae 
_ _ ee oe eee 
. 





Specifies the address of partitions (1 to 7) 
used to subdivide a file 





A READ, 1D macro will be issued. 


A READ,KEY macro will be issued. 


Fixed-length, blocked records 








Fixed-length records, unblocked 











Specifies percentage of total file allocation to 
be initially assigned to partition 


Search multiple tracks. (If specified, file must be 
allocated on a cylinder basis.) 










Read or write user trailer labels when CLOSE 
issued to file. (Specify LABADDR also) 


This file may be used as either an input file or 
an output file. 










Read and check standard labels for file. If file is 
processed sequentially, the PUT macro may not be 
issued for this file unless UPDATE=YES has also 

been specified in the DTF. 


OUTPUT 






Write standard labels for th’s file. If file is 
processed sequentially, the GET macro instruction 
may not be issued. 



















UOs* Specifies percentage of secondary allocation to 


n=percent 4 x x X 
be used for extending partition 
UPDATE Write records back into same location from which 


they were read. 


VARBLD 





Required for variable-length, blocked records that 
are built in output area; register contains number of 
bytes left in output area. 
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Table 15-3. Summary of DTFNI and DPCA Keyword Parameters. (Part 3 of 3) 


Keyword ipacificarion for - : 
DPCA INPUT OUTPUT IN/OUT i ee «ee - : 
= CE a 
















Remarks 








LEGEND: 

R Required 

Xx Optional 

Y One option required 


Assumed parameter, if none specified 
Parameter may be changed on DD job control statement. 





Examples of DTFNI declarative macros used to doting: a nonpartitioned, nonindexed file and a 
nonindexed file containing two partitions. 


Example: 


LABEL. poe Anne .. OPERAND 


1 
pexars | pred] Bix SIZE=5 Zo. 

‘ti... | Ree ORM=VARBL Ko) 1 1 1 
T DAREA| =BUIEEER, 

AR.BL D.=.¢ 4 
RELATIIVE=R.. 
BEEKADR=RELREC 1 
VERDEYSYERle a to 
RRoOP $K DP. 
ZROR=ERREXT 


il 


may 


BLKSTZE=2516,, 
RECEORM=FIMBL 

SECS TZE= 1 28 , 
PCA =OR ANSig: i i ti | 
PCAZSIINET LiEZ 

SAREA! =BUIFRFER| 

ILOAR EA 2Z,='6 VIF FER Z 4) L 
OREG= C4) 4) 1 iti 


SIZE F551, 1 111i tb iiis 
UOSi= 110, 


YPEFL E= OU 


7 
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Examples of DPCA declarative macros used to define partitions of a multipartitioned DTFNI file: C 


LABEL AOPERATIONA - OPERAND 
Go... uw 





iat 


s | fe LiZE.= 51 
EOFADDR=ENDIOB 

Pe Ageeieis. eit 

| ToAREA = PRIME. 

E CAREAZ=S OND 

| reRege= Dis 

| IREGEORM=: ELK BL 

| Recsrz =| 2B 

eae 


INF DL |EZ, KL E =I C 


ITOAREA =T. NAR EAI 
OAR SAZ= TINARE, AZ 
PEC.5 TizE= ae ie Peay 4 


WOR, A= 





15.6. KEYWORD PARAMETERS FOR DECLARATIVE MACROS | 2 | 


The following paragraphs describe each of the 36 ‘required and optional keyword 
parameters used as the operands of the declarative macros that are part of the nonindexed 
file processing system of OS/3 data management. These declarative macros include the 
DTFSD, DTFDA, DTFNI, and DPCA declarative macros, which you use to define your disk 
files and partitions. The keyword parameters are presented in alphabetic order for ease of 
reference. Subsection 15.6:36 lists certain nonstandard forms of these parameters that 
are supported by OS/3 data management so that existing programs prepared for other 
systems may be run under OS/3 with minimum change. 


Table 15—7 shows which keyword parameters are used with which macro; if you code a 
keyword parameter for a declarative macro that does not support it, this error will be noted 
at assembly time, and flagged in your assembly sound with an appropriate, self- 
explanatory error message. . 


UP-8068 Rev. 4 SPERRY UNIVAC 0S/3 15-21 
BASIC DATA MANAGEMENT Update C 





The following descriptions also include notations as to which declarative macros support 
each keyword parameter and point out any difference in meaning of a keyword when it is 
applied to the various file definitions or processors. 


15.6.1. Specifying File Accessing Options (ACCESS) 
For a description of the ACCESS keyword parameter, see 11.4.1. 


Records added by the writer (ACCESS=EXCR) to a file, in a shared environment that 
permits one writer and any number of readers, are not available to the reader 
(ACCESS=SRD). Once the writer closes the job, any added records will be available to 
users who subsequently open the file. 


15.6.2. WRITE,AFTER or WRITE,RZERO Macro Issue (AFTER) 


When you intend to issue one of the following forms of the WRITE macro to a DTFDA file 
or to a DTFNI file you are processing randomly, you must specify the AFTER keyword 
parameter in your DTF: 


WRITE,AFTER -(15.7.11.1) 
WRITE,AFTER,EOF —(15.7.11.3) 


WRITE,RZERO (15.7.11.2) 


If you specify the AFTER keyword parameter in the DTF for a file that you are creating ona 
variable-sector 8411, 8414, 8424, 8425, 8430, or 8433 disk, data management expects 
that you will do so using these macros and does not preformat the file at OPEN time. 
Because the WRITE,ID macro conducts a search and relies on preformatting, you may not 
issue this macro to a file on a variable-sector disk when you. have specified the AFTER 
keyword parameter; data management can find no relative disk addresses to match against 
the content of your SEEKADR field. See the description of the WRITE,ID macro (15.7.11.4). 


The foregoing restriction does not apply to a file on a fixed-sector 8416 disk, which is 
preformatted by definition. 


Keyword Parameter AFTER: 


AFTER=YES 
Specified if a subsequent WRITE macroinstruction contains an AFTER or an 
RZERO positional parameter. This keyword parameter is used only when creating 
or adding blocks sequentially, marking the end of data in the file, or repositioning 
the disk head to a new track. 
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15.6.3. Specifying Block Length (BLKSIZE) 


Each input or output file and partition must have at least one |/O area (buffer) reserved for 
its individual use. The symbolic address of this area is defined by the IOAREA1 keyword 
parameter, which is required for all DTFs (15.6.10), but you also need the BLKSIZE 
keyword parameter to specify the maximum length of the blocks placed within it. The 
BLKSIZE keyword parameter is therefore required for DTFSD, DTFDA, DTFNI, and DPCA 
declarative macros. 


These factors determine the size of your |/O area, which you specify elsewhere in your 
program with the BAL define constant (DC) or define storage (DS) statement: 


1. The length of the data to be read or written — If the records in the file or partition are 
variable-length, the block size and buffer must accommodate the length of the largest 
record, which includes the data length and the four bytes reserved at the head of 
each record for the record descriptor word (RDW). Fixed-length records do not contain 
an RDW (14.3.2). 


2. The track capacity of the device on which the file is written — This must not be 
exceeded by fixed- or variable-length records. (See Appendix A for the operational 
characteristics of the disk subsystems supported by OS/3.) 


3. Whether records are variable-length — For blocked or unblocked variable records, 
your block size and buffer length specifications must include the length of the largest 
logical record plus the four bytes required for the block descriptor word (BDW) at the 
head of each block. This point is important for you to remember when you are 
processing files defined by the DTFDA macro, which does not support blocked record 
formats — a BDW is calculated by data management for the blocks of these Eecords 
as well. Look for this in Figure 15—1. 


4. The length a the record key — You specify the key length of the KEYLEN keyword 
parameter when you are referencing blocks by key, generating new blocks with keys, 
or updating or reading both key and data areas of blocks (15.6.14). Therefore, 
whenever you specify the KEYLEN keyword parameter, your block size must also 
include the length of the key. 


5. Whether you are processing optional user labels — User header labels (UHLs) and 
user trailer labels (UTLs) have a standard length of 80 bytes. The |/O area must be at 
least 80 bytes long when these labels are to be processed in your program; in OS/3, 
UHLs and UTLs are handled only in the |/O areas, not in a work area. Refer to 14.2.4, 
15.6.15, and 15.7.3. 


An important point to note is that, although you must always reserve an 8-byte field 
immediately preceding the |/O area for data management use when you are processing 
output files, these eight bytes are not included in your block size specification. Remember, 
also, that the I/O area is always half-word aligned; this is true throughout OS/3 data 
management. 


For example, it would be incorrect to reserve a 68-byte field when your BLKSIZE 
specification is 60 bytes; the following coding example shows one way to do this in OS/3. 
Other systems you may be familiar with do it differently. 
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Example: 


LABEL AOPERATIONA OPERAND 
1 16 


0 

DTFNS| BUKS | #E 00, 

| ILOAREAI = LODAM, 
YPEFLE=du7PuT, 


No 


I. 
2. 
5 
4 


X 
x 
x 
E 
fl 
B 
i 





1. SAMPFLE is a DTFNI file; block size is 60 bytes. 


2. 1/O buffer’s symbolic address is IODAM. 

3. SAMPFLE is an output file; data management requires eight bytes for its use 
immediately preceding the buffer. | 

LL 4. Other keyword parameters are not shown. The following define storage (DS) 

statements must be coded elsewhere in your program, not as part of the DTFNI 
macro call. 

5. Half-word alignment required for all |1/O buffers in OS/3 data management. No 

label: required. Hef eee, 

6. Eight bytes are required for data management use immediately preceding the I/O 
buffer. No label required. ot : 

7. Storage area |ODAM defined as 60 bytes in length, not 68. _. 

NOTE: 


Lines 5 and 6 were written as shown merely to document two separate points 
explicitly. Most BAL programmers will probably replace these: two lines of coding with 
a single define storage (DS) statement having simply a D (double word) for an 
operand. Such an instruction will reserve eight bytes and force half-word alignment 
— a neater way to discharge both requirements at once. . 


Figure 15—1 illustrates the contents of the I/O area under some of the situations just 
described; Table 15—4 summarizes what data management moves into the I/O area when 
you specify certain combinations of the keyword parameters in your DTF. 
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Records With Keys Records Without Keys LO ot 
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RECFORM = VARBLK RECFORM = VARBLK 


LEGEND: 


D 





Data portion of logical record. Data Management assumes this equals block size when records are fixed, unblocked. 
Length of IOAREA1; specified by BLKSIZE. !/O area is always half-word aligned. 


Record descriptor word (RDW), a 4-byte record-length field containing the length of the record in the first two bytes; 
inserted by user. 


Block descriptor word (BDW), 4-byte’ block length field containing the length of the block in the first two blocks; 
calculated by data management. 


Variable-length record; length is specified by RECSIZE and is contained in first two blocks of RDW. 


Keyfield, from 3 bytes to 255 bytes in length; its actual length is specified by KEYLEN except when you want keys 
ignored. (In this event, you Speeity SEILENT or omit the keyword.) Note that only a block, not a record, has a key. 


‘Ejight- byte field that you reserve for data management use with output files; immediately precedes I/O buffer but its 
length is not included in BLKSIZE. 170 area is aes half-word aligned. 


Calculated by data management; user supplies space. 


User-suppliéd. 


Figure 15—1. ‘Record Formats and 1/0 Area Contents for Nonindexed Disk Files 
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Table 15—4. lOAREAT Contents — - 


Keyword READID or ee ai 
"Specification KEYLEN / AFTER WRITEID 1/0 Area Contents" 


AFTER= YES ol -, Data 
; | Key, Data 


READID=YES = = Key, Data — 


or Not specified Key, Data 
WRITEID=YES = = YES Data 
, =0 Not specified = : Data . 


READKEY=YES = YES = YES Key, Data 
or =YES - : Not specified Key, Data~ 
WRITEKEY=YES Not specified | =YES |, Key, Data 
Not specified Not specified Key, Data 





The BLKSIZE and RECSIZE parameters must be specified such that there are no more than 
255 records in a block for FIXBLK files defined by the DTFSD or DTFENI declarative 
macroinstruction. If this maximum blocking factor is exceeded, an attempt to open the file 
results in control being returned to your error routine (or inline if:none was specified) and 
bit 2 (invalid DTF) ane bit s sC(TOE found in open) set in aye: 0 of filenameC. 


Roce Parameter BLKSIZE: 


BLKSIZE=n a 
Specifies the length of the |/O area, where rn is the maximum size of the Bibek in 
' bytes. If the records in the file or partition are variable-length, m must include 
four bytes for the BDW. If the KEYLEN keyword: parameter is oes you must 
also include in n the specified length of the key.. 


15.6.4. Address for Routine on End-of-Input File or Partition (EOFADDR). 


You must supply the address of the routine you code to handle end-of-data processing for 
input files processed sequentially by specifying the EOFADDR keyword parameter. This 


- keyword is required for input files defined by the DTFSD declarative macro and for 


sequentially processed input files defined by the DTFNI macro. You may. not need it for a 
sequentially processed partition defined by a DPCA macro unless you have special end-of- 
data requirements for that partition: if you do not specify the EQFADDR haba 


parameter in a DPCA declarative macro, data management will transfer control, 


sensing end of data, to the address specified ay the EOFADDR keyword parameter : oN ne 


parent eae macro. 


In sadiion to Senna normal file termination procedures by using the CLOSE 


imperative macro in your end-of-file or end-of-partition routine (15.7:2), you may optionally 
extend your file or partition beyond the logical end-of-file; this option is open to you only 
for sequentially processed input files in the update mode (that is, you have. specified 


UPDATE=YES in the DTFSD or DTFNI declarative macro). The details on ius amISTeS of 


extension are develoner: under the PUT imperative macro ne iS 9). 
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Keyword Parameter EOFADDR: 


EOFADDR=symbol 
Specifies the address of a routine you have coded to handle end-of-data for a 
DTFSD input file or a sequentially processed DTFNI input file, where symbo/ is 
the symbolic address to which data management transfers control on sensing 
end of data. Required for DTFSD input files and for Sasa processed DTFNI 
input files. 


15.6.5. Handling Parity Errors on Sequential Disk Files (ERROPT) 


Your may use the ERROPT keyword parameter to specify action data management is to 
take when it is informed of a parity error from which the physical IOCS has tried 
unsuccessfully to recover. Its. ‘use is optional for sequentially processed input or output 
files defined by the DTFSD or DTFNI declarative macros. It is not supported by the DTFDA 
macro. 


Keyword Parameter ERROPT: 
~ERROPT=IGNORE .- 


Specifies that date management is to make the block or record available to you in 
the I/O area as if no parity error had occurred. 


ERROPT=SKIP 


‘Specifies that ree ee dacemait is to ‘iypase or skip over an iene block or logical 
record, which it does not make available to you for processing. For output 
records, data management ignores the block or record as if it were written 
correctly. 


If you omit the ERROPT keyword parameter, on detecting a parity error, data management 
transfers control to your error- panalng routine if you have specified one; otherwise 
control returns to you inline. . 


15.6.6. Error Processing (ERROR) 


You.may have data: management transfer control, on detecting an error or exception 
condition, to a special error processing routine you have defined by the ERROR keyword 
parameter. The ERROR keyword parameter may be used with input or output files defined 
by the DTFSD, DTFDA, or DTFNI declarative macros. You do not specify it in a DPCA 
declarative: on detecting an error or exception condition while processing a partition, data 
management transfers control to the address specified by the ERROR keyword parameter 
‘of the DTFNI macro defining the file to which the partition belongs. 


An_exception condition, as distinguished from a hardware or detectable logic error, is not 
“necessarily an unforeseen .result in ‘processing your file. It may simply signal the 
completion of |/O or an anticipated end of data, cylinder, track, or volume. condition; on 
the other hand, it may also indicate that the expected record was not found. 
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Before data management transfers control to your error handling: routine, it displays 
and/or logs an error message. Data management error messages are documented in the 
system messages operator /programmer reference, UP- ‘8076 (current version) and briefly 
desenibed in Appendix B. 


When your error routine receives control, ‘data management will Have already made other 
information available to you in certain fields of the DTF file table. One field, which your 
error routine should access dynamically to take appropriate action, is filenameC. This field 
of the DTF contains four contiguous bytes; data management sets certain bits of these to 
binary 1 as flags to indicate specific error conditions; refer to Appendix B (Table B—3) for 
the significance of the flags. You may address this field in your program by concatenating 
the character C to your 7- eharacter spatea! file name. 


Another field in the DTF file table, in which data management informs you of the general 
error/status condition, is more useful to examine in debugging a program than to access 
dyamically in your error routine. This field, designated filenameE and always decimal byte 
56 in the DTF, is loaded by data management with a hexadecimal error message code: the 
numeric component of the numbered data management error message to which it 
corresponds. Note these in the leftmost column in Table B—1. FilenameE can be quickly 
located by the tag penerated in the expansion of your DTF declarative macro. 


You should realize that not all of the flags set in filenameC represent error conditions 
causing transfer of control to your error routine. The two exceptions in the Nonindexed | 
disk file processor system are: 


= #@Jast block on track accessed (byte O, bit 0); and 
» //0 cormpicted byte: u bit 0). 


These two do not represent errors; they signal conditions you ‘might expect to use in the 
normal course of processing to determine the need to ‘branch ‘in your program. If you use 
either of these flags in this way, your must test for them /n/ine: you will miss your cue if 
you test only in your error routine. 


It is your responsibility to interrogate the error/status codes and take appropriate action. If 
you choose to continue processing, however, it is useful to remember that data 
management provides you an inline return address in general register 14; the inline return 
is to the instruction in your program next following the imperative macro ) that initiated. the 
transfer of control to your error routine. 


If you do not specify the eeraual ERROR keyword parameter in your DTF, data 
management returns control to you inline, when an error is detected, to the instruction 
next following the imperative macro. In this situation, of course, it is up to you to 
interrogate error/status codes ng and to take appropriate action inline. 
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Keyword Parameter ERROR: - 


_ERROR=symbol _ | Rae c 
Specifies the address of your error handling routine, to hich data miananeniert 
transfers control upon detecting an error condition, nSKG nor is the symbolic 
, Becta of this routine. . ts ; 


If. you” uit repeciicaiion of this optional keyword parameter, data management returns 
control to.your program. inline, at the instruction next after me Puperdtne macro me 
initiated transfer of control ‘to your error routine. 


15.6.7. Specifying Field for Return of Relative Disk Address (IDLOC) 


When you want data management to return to you the relative disk. address (or ID) of a 
block after you have issued a READ or WRITE imperative macroinstruction, you specify the 
IDLOC keyword parameter in your DTF. The ID return is made by the WAITF macro you 
issue following the READ. or WRITE macro. 


If you issue a READ, ID macro or a WRITE macro with the ID, AFTER, or - RZERO sbaiGnal 


parameter, data management returns to you the ID of the next block in the file or Bartley 


On ihe other hand, if you issue a READ, KEY or a WRITE,KEY macro, data management 


returns the same ID as is supplied in the SEEKADR field. 


The form in which the ID is stored for you (as a relative record or a relative track address) 
is governed by how you specify the RELATIVE keyword parameter (15.6.22). 


The IDLOC keyword is specified only for files defined by the DTFDA declarative macro or 
for randomly processed files defined by the DTFNI macro. (When you are processing a 
partition of a DTFNI file, data management uses the IDLOC keyword you snes in the 
DTFNI macro defining the file to which the partition belongs.) _ 


When you specify the IDLOC keyword parameter, you Siovide ihe symbolic address of the 
field to which data management makes its return. You should remember that OS/3 data 


management, assumes that the size and format of this field are the same as those of the - 
field you have supplied via the SEEKADR keyword parameter, which you are required to. 


specify for DTFDA files and randomly processed DTFNI files. In some situations, you will 


find it an advantage to make the IDLOC and the SEEKADR fields (15.6.26) physically one. 


and the same, so that data management aptompuealy updates the SEEKADR field for you. 


For example, if you are creating an output file itt the WRITE, ID macro > (15. 7. 11 .4), you 
must provide data management with the relative disk address, or ID, to which each block 


is to be written by moving this ID into the SEEKADR field before.issuing the macro: the ID — 


is what guides the macro. After successful execution of the WRITE,ID macro, the following 
WAITF macro (15.7.16) returns to your IDLOC field the ID of the next block in physical 
sequence in your file. If this address is indeed where your next record goes, you move the 
contents of the IDLOC field to the SEEKADR field — but, if you had made these two fields 
the same area in main storage, then data management has in effect updated the 
SEEKADR field for you automatically, and you can issue another WRITE,ID macro. 


iii, 
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Consider, on the other hand, the WRITE,AFTER imperative macro (15.7.11.1). This macro 
does not require you to preload the SEEKADR field to guide it, but relies upon your having 
positioned your file to where it is to write. Yet, to specify both the IDLOC and the 
SEEKADR keywords and to make the fields the same simplifies your handling of the end- 
of-track occurrence. The ID returned by the WAITF macro that follows each WRITE,AFTER | 
macro is (as with the WRITE,ID macro) the relative disk address of the next block. If you 
have specified re/ative track addressing (with RELATIVE = T), the ID is not automatically 
incremented to become the address of the first block on the new track unless you have 
moved each previously returned ID to the SEEKADR field. To avoid this, and to avoid 
testing inline for setting of the /ast-block-on-track-accessed bit in filenameC after each 
WRITE,AFTER issue and repositioning your file to the head of the next track with a 
WRITE,RZERO macro (as described in 15.7.11.1), you may rely on the automatic 
incrementing that data management provides, by making the IDLOC and SEEKADR fields 
the same area. 


On the other hand, if you are updating your file with the READ,ID/WRITE,ID macro 
combination, you would not want to have data ‘management automatically update: the 
SEEKADR field with the ID return for you. This is because the ID returnediafter the WAITF 
that follows the READ,ID macro is the address of the next block in the file. You would be 
overwriting that block with the information intended for the current block if’ you had made 
the IDLOC and the SEEKADR fields physically one and the same — not a good practice in 
update. mode. - a oe A ee es aig bo . 


Table 15—5 recapitulates the situations just described. 


Table 15—5. Relative Disk Address (ID) Returned after a READ or WRITE Macroinstruction 
when IDLOC Keyword Is Specified 


Imperative | DTF Keyword ID Returned by enor oP le Retined 
Mba vee Fatamneters WAITF Macro RELATIVE-R aeuivest : 


READ, KEY | READKEY=YES OL lees 
. RITE - Same ID as that 
ee area : WRITEKEY=YES of block retrieved 


“| READ, ID | READID=YES 
| WRITE,ID — WRITEID=YES . 


WRITE, AFTER AFTER=YES 


ID of next block 
in the file 


*Discontinuous binary, where: 





rrr. sis the 4-byte relative block number. 
ttt is the relative track number. 


r is the absolute block number on the relative track. 
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Keyword Parameter IDLOC: 


IDLOC= symbol 

Specifies the. field to which data management returns the relative disk address 
(ID) after the execution of a READ or WRITE macro, where symbol! (label) is the 
address of the field. Data management assumes that size and format of the field 
are the same as specified in the SEEKADR keyword parameter (15.6.23). Form in 
. which ID is returned is governed by specification of RELATIVE keyword 
_ parameter (15.6.22); the block whose ID is returned is governed by the posmiona! 

parameter used with the READ or r WRITE macro. 


15.6.8. <7 the Factor for Record Interlace (LACE) 


Supported for input and output files defined by the DTFSD, DTFDA, and DTFNI macros and 
for partitions. defined by the DPCA declarative, the optional keyword parameter LACE 
allows you. to specify the lace factor you need when you want to take advantage of record 
interlace operations. 


The record interlace feature of OS/3 data management is both a data mapping and a 
tuning technique for increasing your throughput when you are processing input or output 
disk files by permitting you to access successive blocks within a predetermined interval of 
time. If this interval, which depends upon your program, is less then the time the disk 
takes to complete a turn, you will retrieve more than one block per disk revolution. Record 
interlace thus reduces the effect of rotational delay on your overall disk processing time; 
you benefit most when you are processing files or partitions sequentially and least when 
you are processing randomly. 


This does not mean that the LACE keyword has no role in processing a direct access 
DTFDA or DTFNI file; the record interlace technique will never degrade random processing 
of such a file and is of use whenever sequential operations against the file are significant. 
For example, if you create a direct access file by a substantial sequential loading 
operation, using record interlace will make for a more efficient creation program. A 
massive update operation, using the READ,ID/WRITE,ID combination, might also be a 
recurring program in your application; this, too, could make advantageous use of record 
interlace. A third example of a use of record interlace that makes sense in a file organized 
for direct access is with a report-generating program: in which random access is used to 
one or more points in the file, with sequential processing required thereafter for the 
reports. 


You must first physically arrange your blocks on disk using record interlace before you can 
achieve the increased processing speed that the technique offers you when you are 
reading from a laced input file; on the other hand, you are able to write your output file 
more rapidly by using record interlace. It is important to remember that, once you create a 
file with interlace, this physical characteristic remains with the file, and it must always 
thereafter be accessed by programs that specify the same lace factor you used to create it. 


st, 


C) 
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Figure 15—2 shows how record interlace works to your advantage. Assume that your 
input file contains ten 1024-byte blocks per track. If these are located on disk in physical 
sequential order, as shown. in the lefthand portion of the figure, you would need 10 disk 
revolutions to retrieve all 10 blocks sequentially. (If the disk you are using has a rotation 


‘speed of 21.4 ms per revolution, for example, accessing the blocks in this way would take 


214 ms.) 


On the other hand, if you could space your blocks on the track so that the next one to be 
retrieved arrived under the disk head just as our I/O order to retrieve it took effect, you 
could save time — possibly enough time to retrieve more than one block per disk 


_ revolution. The physical interval between your blocks would need to be little more than the 


distance the disk rotates during the period of time it takes you to process each block and 


to issue a new I/O order. The components of this time slice are your processing overhead 


and the data management overhead involved in issuing your |/O order; your processing 
time overhead depends primarily on what your program does. When you use the record 
interlace technique, data management uses SAT (through which it physically accesses 
each disk subsystem) to establish the physical interval between your blocks and to arrange 
them on the track so that as many may be retrieved as your program is capable of 
handling before the next access time comes. 


efi gee Without Record Interlace : With Lace Factor of 4 
. 7 1 7 8 9 10 


2.3 4 5 6 | 
File} 4} ofa] 7] sro} s| a | 













Physical Block No. 






Logical Block No. 








Logical Blocks 
Read or Written 
During Each 

* Disc Revolution 
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The righthand: portion of Figure 15—2 shows an arrangement of the same 10 blocks, he 
using an interlace factor of 4. How the factor is derived from the estimated program time 

frame will be developed in what follows; note at.this point that their physical arrangement 

allows all 10 to be retrieved before the completion of the fourth revolution of the disk — 

less than 85.6 ms, instead of 214 ms as before. Note also that three blocks are skipped 

between successive accesses; the lace factor is always 1 more than the number of blocks 

skipped. 


To achieve this saving of processing time, you specify the lace factor to data management; 
calculating it is a simple 2-step procedure. You need only two figures: vom Ble size and 
an estimate’ of. the time interval between your 170 orders: 


The first step is to weeleulas the sector time; this is the aamibee of millisatonds each block 
requires to pass under the disk head. Simply divide your block size, measured’ in Dyes, by 
208: eyes and multiply by a standard factor, 0. 935 | ms: 


eile block size x 0.535 ms = calculated sector time 

256 bytes © : 
The second step yields the /ace factor, which you will specify as a decimal integer with the 
LACE keyword parameter. First, you make an estimate of the time frame your program will 
need for processing between issuing your I/O orders..Then you divide the time frame by 
the calculated sector time, add 1, and round high to yield the lace factor, which is always 
a decimal - integer: eo 


fT, 


time frame ms oo. eid, | Aad 
calculated sector time ms + 1 (rounded high) = /ace i actor 
Following the illustrated example, assume that you are Being a 1024-byte block size; you 
calculate the sector time in milliseconds: 


1024 bytes © ett ee 

"256 bytes Xx 0.535 1 ms = 2.14 ms 

Estimating that a 6.0 ms average time frame is required between accesses to your blocks, 
you then calculate the /ace factor: 


6.0 ms = — 
214 ms =29+1= 3.9 
When the time frame exceeds 21.4 ms, it should be divided by 21.4, and the remainder 
should be used as the time frame in the foregoing calculations. 


You may estimate the average time frame your program needs to process records between 
passes by using the GETIME macro of the OS/3 supervisor, described in the supervisor 
user guide, UP-8075 (current version). Or, arbitrarily specifying successively larger lace 
factors, and noting the running time for your program with each factor, you may pinpoint 
the optimum lace factor for this program: the one giving the sharpest decrease in running 
time, followed by a quick increase when the next higher factor is used. " 


é ad 
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Note that the average time frame will be different. for every program accessing the laced 


file. lf several programs at your installation are to.use the-same file but have. different time 
frames, the .file should be laced with a factor that: is the best compromise you can 
establish, taking into consideration the running times of the programs, the frequency with 
which they will access the file, and the relative importance of the pregrans to your 
installation. 


It is important to remember that all programs accessing the same laced file must specify in 
the DTF the actual lace factor used in constructing it; an erroneous specification will cause 
data management to reset the LACE specification to the value’ used when the file was 
created. The lace factor is recorded in the-disk format 2 label (D.3.2),,and it is one of the 
items listed by the system utility (SU) symbiont when you request a VTOC print. (The SU 
symbiont is documented in the system service programs (SSP) user guide, UP-8062 
(current version).) 


It may be evident to you that the standard factor 0.535 ms and the 256-byte divisor 
contained inthe first. formula do not apply to all disk subsystems supported by OS/3. This 
is:true only in part: these figures actually derive from the operatonal characteristics of the 
8416. disk subsystem, which was selected: quite arbitrarily to provide one set of standard 
factors for you. to use in this calculation. Nevertheless, you use these same figures for 
whatever disk subsystem contains your file; OS/3 data management, through SAT, will 
adjust the /ace factor automatically to the characteristics of the actual device in use. (As 
you know, you never specify the actual device to data management, but SAT’ and data 
management know the device type from OS/3 job control.) 


Whenever you specify the KEYLEN keyword parameter (15.6.14), -you imply random 
Bicceesindy ane the aia Revnore parameter is pinetee: if aoe ppecly both. 


Keyword Parameter LACE: 


LACE= n : 
Specifies the /ace Paton a aacinial ateger for data ‘aanagement use in applying 
the record interlace technique to sequentially processed input or output files 
defined by the DTFSD, DTFDA, or DTFNI macro, or’ partitions defined by the 
DPCA declarative macro and processed a aad als Oe 6 ignored when the 
KEYLEN Romana parameter is. _openeee ws eb OEE Sa 


15.6.9. | Sasciving (nput/Outout Buffer (IOAREA1): 


Each input or output disk file and partition must. have at least: one input/output area 
reserved for its individual use. You define this area by specifying the IOAREA1 keyword 
parameter, which is required for files defined by the DTFSD, wim and aE declarative 
macros and for file partitions defined all the ene macro. 


You define the length of the 1/0 area a means of tie BLKSIZE keyword parameter 
(15.6.3); as is true throughout OS/3 data management, the |/O area must be half-word 
aligned. You must reserve an 8-byte area for data management use immediately preceding 
the I1/O area for output files; these eight bytes are not included in the blocksize 
specification. (See Figure 15—1.) 
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In order to achieve device independence between sectorized and nonsectorized disks, you 
should reserve areas whose lengths are some multiple of 256 bytes for I/O areas. 
‘However, your BLKSIZE specification need not be a multiple of 22. bytes to maintain 
device dependence: 


Keyword Parameter IOAREA1: 


~ LOAREA1=symbol | 
Specifies. the location, half-word aligned, -of the I/O area; required for files 
defined by the DTFSD, DTFDA, and DTFNI macros and for file partitions defined 
- by. the DPCA macro, where symbol (label) is the address of the I/O area. Length 
of |/O.area is eneeniee BLKSIZE keyword parameter (15.6.3). 


15.6. 10. Specifying a Secondary pute Ousput Buffer (IOAREA2) 


You may improve your processing efficiency by speeihvinG. a secondary I/O area for 
standby processing; this allows you to overlap I/O operations with your record processing: 
You may optionally specify the IOAREA2 keyword parameter for DTFSD files and 
sequentially processed files and partitions defined by the Pa, and DPCA: macros;.it is 
not Supported BY the DTFDA macro. ee 


Keyword Para metay IOAREA2: 


Ra ise pire Ltd cde 
Specifies the location of an optional secondary I/O area for files defined by the 
DTFSD macro or sequentially processed files and partitions defined by the DTFNI 
and DPCA macros, where symbol (label) is the address of the secondary I/O 
area. If specified, the area is subject to the same considerations as noted for the 
area defined by the IOAREA1 keyword parameter (15.6.10). The IOAREA2 
keyword parameter is not supported for DTFDA files. Pint 


15.6. 11, Specifying Index Resists ue Current Data Pointer vOnES) 


When you need an index register to raerenies current data for your: 1/0 processing, you 
specify the general register to be used for this purpose with the IOREG keyword 
parameter. General registers 2 through 12 are always available, but if you have specified 
the SAVAREA keyword parameter, general. register 13 is also available (15.6.25). 


The IOREG keyword parameter is not supported for files defined by the DTFDA declarative 
macro. You should SpeeIY it for the rellewsing input or output me: og 


- “DTFNI files and paniions processed randomly (using ‘the READ or WRITE imperative 
macro), when you have specified two I/O buffers (15.6.11). 
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=  DTFNI files and partitions processed sequentially (using the GE or PUT macro) and 
files defined by the DTFSD macro when you have: . 


— specified two I/O areas but no work area; or 
— specified no work area but have blocked records. 
Table 15—9 summarizes the use of an index register with the GET macro (15.7.12). 


When. you’ do use a work area for sequential processing instead of an I/O area, you 
specify its address as an operand of each GET or PUT imperative macro you issue, and you 
indicate to data management that you are using a work area by specifying the WORKA 
keyword parameter in your. was You led do not specify the nee keyword parameter. 
(See 15.6.34.) 


For input files, data management loads the index register with the address of the next 
available record or block. 


For output files, data management. loads the index register with me. address of the next 
available I/O area. 


When a file is opened, data management loads the index register with the current buffer 
address and, for a multipartitioned file defined by the DTFNI macro, sets partition 1 active. 
If you specify an IOREG keyword parameter for several partitions, the index register for 
partition 1 is loaded when the file is opened; only when you issue a SETP imperative 
macro to gain access to a. ‘subsequent Partition does Sit Management load the index 
Register for that partition (15. 7. 4). 


Keyword Parameter IOREG: 


pen ret 
‘Specifies the general register to be used as an index register to reference current 
data for |/O operations, where r is the number of the general register and must 
be enclosed in parentheses. Registers 2 through 12 are available, and register 13 
is also available when you specify the SAVAREA keyword parameter. The IOREG 
keyword parameter may not be specified for DTFDA files, nor when you specify a 
-work area with the WORKA keyword parameter; it is required for DTFNI files and 
partitions processed randomly with two |/O areas and for DTFSD files and DTFNI 
_ files and partitions processed sequentially nen records are blocked or when you 
use two I/O areas. | 


15.6.12. Specifying Address of Argument for Key Search (KEYARG) 


When you want to search your file for a block with a Saecitic key (if, for example, you are 
issuing the block-level READ,KEY or WRITE,KEY imperative macro), you must provide data 
management with the search argument in a field in your program that you specify with 
the KEYARG keyword parameter. Data management uses the search argument to locate a 
block with an identical key. 
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You should also remember to specify the length of the key with the KEYLEN keyword 
parameter, described next (15.6.13). The READ,KEY and WRITE,KEY imperative macros are 
described in 15.7.14.2 and 15.7.11.5. 


Keyword Parameter KEYARG: 


KEYARG=symbol 

‘Specifies that a search is to be made for a block having a key identical to a 

search argument you provide to data management, where symbol (label) is the 

. field in your program containing this argument. The KEYARG keyword parameter 
is not supported for DTFSD files; it. is required for. DTFDA files and randomly 
processed DTFNI. files (and -partitions defined by the DPCA. macro) ‘when 
READ,KEY or WRITE,KEY:imperative macros will be issued. When you specify the 
KEYARG keyword parameter, you must also specify the length of the key, using 
the KEYLEN keyword parameter. 


15.6.13. Specifying the Length of Block Keys (KEYLEN) 


When you are referencing blocks by key, generating new blocks with keys, or reading both 
the key and data areas of your blocks, you must specify the length of the keys in yeu file 
with the KEYLEN. keyword ene! ; 


All keys in a DTFDA file or a Sjngle-parttioned DTENI file must have the same fenaits 
however, each partition of a multipartitioned DTFNI file may have its own characteristic 
key length (which must remain the same for all blocks in the partition); you define this 
length separately with a KEYLEN keyword parameter in the DPCA declarative macro for 
each partition that does differ in length of keys from the basic file. The minimum key 
length for any file or partition is 3 bytes; the maximum is 255 bytes. No byte of any block’s 
key may contain the hexadecimal value FF. | 


It is important to specify the actual.length of the key as it exists in all blocks of your disk 
file; otherwise, data management either truncates or pads out the key ang sets the wrong 
length found flag (bit 5, byte 1) in filenameC. (See Appendix ef 


Another important point to eineniber ‘has to do. with. ecauenually puesce DTFNI files: 
these also may have a key associated with each block. of data. ee for example, Figure 
15—1.). | . . | 


If yours do, you must remember to place the key at the beginning of the data block, before 
you issue a PUT imperative macro. Your PUT macro will then cause both the key and the 
data portion of the block to be written out to disk, and your subsequent GET macros will 
retrieve both the key and data. Data management will, as always, block and deblock your 
records automatically when you are processing DTFNI files sequentially (that is, via the 
GET and PUT macros). DTFSD files do not. contain keyed blocks; DTFDA files may not be 
specified as navinek blocked records. | . 


an 


cin, 


UP-8068 Rev. 4° SPERRY UNIVAC OS/3, 15-37. ° 


BASIC DATA MANAGEMENT — 





Keyword Parameter KEYLEN: 


KEYLEN=n 
Specifies the length of keys in DTFDA and DTFNI files and in file partitions 
defined by the DPCA macro, where rn is the number of bytes in the keys. All keys 
in the same partition or the same nonpartitioned DTFNI or DTFDA file must have 
the same length; the key length may range from 3 bytes ‘minimum to 255 bytes 
maximum. No byte of any key may contain the hexadevimal value FF. 


The eee neywOre parameter is not. supported for DTESD files. 


15.6.14. Specifying Address of Your Label Pioeeeeiie Routine (LABADDR) 


As you know from 14.2.4, OS/3 data management gives you the option of having your 
own user header and trailer labels (UHL and UTL) on your nonindexed disk files. When you 
need to process your labels, you use the LABADDR keyword paramrtce to specify the 
address of your label processing routine. 


The LABADDR keyword parameter is supported for DTFSD, DTFDA, and DTFNI files; 
because user header and trailer labels are supported at the file level and not below, you 
do not specify the LABADDR a sg with ane: DPCA ae claratve macro (by which you 
define a file partition). 


When you choose to use your own headers and trailer labels, it is well to remember that 
they are written by data management on the first track of each volume of a DTFSD file 
(because only one volume is mounted at a time) and on the first track of the first volume. 
only of a DTFDA or DTFNI file - (because all volumes of these files are paling for 
processing). ° 


In examining the DTF of a direct access file t that contains user labels, do not be confused 
by the relative block addresses calculated by data management and stored in the DTF. 
These will appear to be inflated because data management adds to the relative disk 
address in question the number of data blocks that could have been contained by the user 
label track if it were used for data. (This is more fully explained in 15.6.24.) | . 


Another important point to remember is that your label processing routine may comprise 
only BAL instructions and the LBRET imperative macro, described in 15.7.3. You may not 
issue any other file processing macro in your label routine; there is, for example, no legal 
way to issue a macro to subsequently list your labels for inspection, via a printer file. They 
do show up, however, in a disk print of your file taken with the system utility (SU) 
symbiont if your specification to this utility includes head OO of the volume, and the last 
one processed may also be seen in veur eo area in a program dump under the right 
circumstances. 


A third point to keep in mind is that, whenever your LABADDR routine will be processing - 
UTL when you issue the CLOSE imperative macro to on file, you must always specify the 
TRLBL keyword bvamoers in the PeTE (15.6. 28). - 
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Your standard UHLs and UTLs have a simple 80-byte format (14.2.4); this means that your 
I/O areas must always be at least 80 bytes long when you epecliya a LABADDR routine to 
process them. 


Keyword Parameter LABADDR: 


‘LABADDR= =-symbol . 

Specifies the address of your routine for processing optional standard user 
header and trailer labels, where symbol (label) is the address. This keyword is 
supported for DTFSD, DTFDA, and DTFNI files. UHL and UTL are not supported at 
the partition level; therefore, the LABADDR keyword is not specified with the 
DPCA declarative macro. Your label processing routine may issue the LBRET 
imperative macro (15:7.3), but no other. If you will be processing UTL on closing 
the file, you must also specify the TRLBL keyword parameter in the DTF 
(15.6.28). . : 


15.6.15. Suppressing a File Lock (LOCK) 


For a description of the LOCK keyword parameter, see 11.4.11. 


15.6.16. Specifying an Optional Sequential File (OPTION) 


When. you have a sequentially processed file that your program can sometimes do without 
— that you anticipate you will not invariably want to process every time you run — you 
may specify this fact with the OPTION keyword parameter. This keyword may be used for 
files defined by the DTFSD macro and for sequentially processed DTFNI files. Because all 
volumes of DTFDA or randomly processed DTFNI files are always online for processing, the 
OPTION keyword parameter is not used for these. 


When you use the OPTION keyword parameter, and data management detects. that you 
have not allocated the file to a device (that is, you have not specified a job control DVC- 
LFD device assignment set for it), the first GET imperative macro transfers control to your 
end-of-file routine. This action maintains the continuity of your program, but it is up to you 
to close the optional file when you receive control (you specify the address of your end-of- 
file routine, which itself. is optional, via the EOFADDR keyword parameter (15.6.4)). 


On the other hand, if you have not specified the OPTION keyword parameter for a file that 
you neglect to allocate to a device with job control statements, your EOFADDR routine 
does not receive control. Instead, data management either transfers control to your error 
routine (if you have coded one and supplied its address via the ERROR keyword parameter) 
or returns control to you inline. In any case, you may neither create records for the file nor 
obtain records from it even if it exists on disk. For output files, the PUT mechanism is 
disabled. 


You may not randomly process a file described as optional with this keyword parameter, 


which is reserved for sequentially processed files. If you issue a direct access file 
processing macro (READ or WRITE) to a file described by the OPTION keyword parameter, 
data management will transfer control either to your error routine or to your program 
inline, at the instruction next after the imperative macro, setting the /nvalid macro flag 
(byte O, bit 6) in filenameCc. 


ley 
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Keyword Parameter OPTION: 


OPTION=YES ~ 
Specifies that the sequentially processed file defined by this DTFSD or DTFNI 
macro is an optional file: one that you anticipate will not invariably be present for 
every program execution. When specified for a file not allocated to a device by 
job control DVC-LFD device assignment set, transfers control to your EOFADDR 
routine on first issue of the GET macro. For sequential output files, the PUT 
mechanism is disabled. When specified for sequential files, issue of a direct 
access imperative macro (READ or WRITE) causes transfer of control to your 
error routine or to you inline. The OPTION keyword is not used with DTFDA files. 


15.6.17. Specifying Address of Partitions for DTFNI Files (PCA) 


You must use the PCA keyword parameter in a DTFNI declarative macro to provide data 
management with the address of each partition of the file that has a separate identify (that 
is, each partition that is defined with a DPCA declarative macro — see 15.5.4). You need 
not use the PCA keyword parameter when the DTFNI file is not partitioned (15.5.3). 


Each DTFNI file may comprise seven partitions; descriptive information on the first 

partition is contained in the DTFNI declarative macro. The second partition through the 

seventh are described in separate DPCA declarative macros, which are limited to 

presenting those partition-level aspects in which the partition differs from the basic file. 

The labels of these DPCA macros are the partition names specified by the corresponding 
~ PCA keyword parameters of the DTFNI macro. 


Although you may subsequently access DTFNI file partitions in any order, when you are 
defining an output file you must specify the partitions in unbroken sequence in the DTFNI 
macro: you must specify the first partiton before the second, the second before the third, 
and so on. When you are defining an /nput file, you specify only those partitions you 
actually require for processing. (You will subsequently access these separately by issuing a 
SETP imperative macro, 15.7.4.) . 


You should not confuse the PCA keyword parameter described here with the PCA 
declarative macroinstruction of the OS/3 supervisor. The PCA macro of the Supervisor has 
a role analogous to that of the OS/3 data management DPCA declarative macro; see the 
Supervisor user guide, UP-8075 (current version). 


Keyword Parameter PCA: 


PCA1=symbol... ..PCA7= symbol . 

Specifies the address of each partition of a multipartitioned DTFNI file, where 
symbol (label) is the address. PCA2=symbol, ....PCA7=symbol define the labels of 
the corresponding DPCA macros. Partition 1 is contained in the table defined by 
the DTFNI macro, in which PCA1=symbol is required only for data management 
use in assigning the label to the partition table defined within the DTF. The PCA 
keyword is not used for nonpartitioned DTFNI files, nor for files defined by the 
DTFSD or DTFDA macros. Partitions must be specified in unbroken sequence. 
The symbolic address is used as the label of the corresponding DPCA declarative 
macro. 
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15.6.18. Specifying Issue of a READ,ID Macro (READID) 


When you intend to read a direct access file, locating each block by its relative disk 
address or ID; you will issue the READ,ID form of the READ imperative macro (15.7.14.1). 
Beforehand, however, you must.inform data management that you will be doing so, by 
specifying the READID keyword parameter in the DTFDA or DTFNI declarative macro. (The 
READID keyword is not used with files defined by the DTFSD macro.) 


Reyword Parameter READID: 


‘READID=YES 
Specifies to data management that you will issue a READ, ID imperative macro to 
the DTFDA or DTFNI file defined by this declarative macro. 


The READID keyword is not used for DTFSD files. 


15.6.19. Specifying Issue of a READ,KEY Macro (READKEY) 


When you intend to read a direct access file, locating each block by a search on key, you 
will issue the READ,KEY form of the READ imperative macro. Beforehand, you must 
inform data management that you will be doing so, by specifying the READKEY keyword 
parameter in the DTFDA or DTFNI declarative macro. The action of the READ,KEY 
imperative is explained in 15. 7. 14.2; you will need also to specify the following keyword 
parameters: | 


SEEKADR (15.6.23) 

KEYARG (15.6.12) 

_KEYLEN (15. 6. 13). 
Keyword Parameter READKEY: 


READKEY=YES 


Specifies to data management that you will issue a READ,KEY imperative sere 


to the DTFDA or DTFNI file defined by this declarative macro (15.7.14.2). This 
keyword is not used for DTFSD files. Thé SEEKADR, KEYARG, | and KEYLEN 
keyword parameters are also required. © 


15.6.20. Specifying Format of Records in Disk Files (RECFORM) 


The optional keyword parameter RECFORM is your means of specifying to data 
management the format of the records in your disk files. It is unnecessary to specify this 
keyword parameter if your records are fixed- length and unblocked: data management 
assumes et this is ome desired format when you omit the RECFORM Keyword from your 
DIF. : 


0S/3 data management supports four record formats for nonindexed disk files; Table 
15—6 shows which fornia are used with: which file type. Note that undefined records are 
not PenRnoriee: if 
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Table 15—6. Record Formats for Nonindexed Disk Files — 


Declarative Macro ye ae _ Specification : 
— ‘for RECFORM 
“KeyWord | Parameter 


Record 
Format 


FIXBLK 





supported 
unsupported 
assumed if not specified 


pay 
How fl 


Keyword Parameter RECFORM: 


Optional for all files; specifies format of records. There are four specifications: 





( ) . Specifies that records are fixed-length and unblocked. Data management 
assumes this format if you omit the RECFORM keyword parameter from the DTF. 


RECFORM=FIXBLK 
Specifies that records are ‘xed: -length and blocked. Not supported i DTFDA 
files. 


A maximum of 255 records per block is allowed. The number of records per block 
is saved in the. format. label in a 1-byte field. Thus, if it exceeds 255, the value 
placed in the 1. -byte field will be the actual. number of records per block. minus 
modulo 256. For example, if there. are 300 records per block, the effective value 
_ placed in the format label will be 44, 


~ RECFORM=VARBLK . 
Specifies that records are variable- -length and blocked. Not supported for DTFDA 
files. 


RECFORM=VARUNB ._ 
Specifies that records are variable- length and unblocked. Supported for DTFSD, 
DTFDA, DTFNI, and DPCA declarative macros. 
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15.6.21. Specifying Size of Records in Blocked Disk Files (RECSIZE) 


When you have specified blocked records in your file, fixed-length, you may specify the 
number of bytes in a logical record to data management with the optional RECSIZE 
keyword parameter. This keyword may not be. specified for files defined by the DTFDA 
declarative macro because OS/3 DAM does not provide for blocking or deblocking records. 


It is not necessary to specify the RECSIZE keyword parameter when your records are fixed- 
length, unblocked: data management assumes that the record size equals the length of the 
I/O area that you specify by your BLKSIZE keyword parameter (15.6.3) when your records 
are fixed-length, unblocked. Nor do you specify the RECSIZE keyword for files containing 
variable-length records, blocked or unblocked: here, data management expects to find the 
size of the record in the first two bytes of the RDW at the head of each variable-length 
record. A look at Figure 15—1 (15.6.3) will make these points clear. 


See the description of the BLKSIZE keyword parameter (15.6. 3) for information regarding 
the maximum blocking factor for FIXBLK files. 


Keyword Parameter RECSIZE: 


RECSIZE=n 
Specifies the length of fixed-length logical records in blocked files, where nr is the 
number of bytes in the record. Optional for files defined by DTFSD and DTFNI 
macro and for partitions defined by DPCA declarative macro. Not used for DTFDA 
files. 


Data management assumes that record size equals block size (BLKSIZE keyword 
parameter) for fixed-length, unblocked records and expects to find record size in 
RDW of variable- length records. 


15.6.22. Specifying the Form for Relative Addressing (RELATIVE) 


The nonindexed disk file processor system gives you the choice of two forms for specifying 
the relative disk address (ID) of an individual block or record in a direct access file: relative 
record or relative track addressing. You specify the form that is to be used for data 
management with the RELATIVE keyword parameter of the DTFDA or DTFNI declarative 
macro. When you specify the relative disk address of a record or block to data 
management, or when data management returns an ID to you in the course of processing, 
it is placed in this form on the appropriate 4-byte field in your program. The absolute disk 
identification address* is not used in the nonindexed processor system. 


By relative record address, you should understand a hexadecimal number, right-justified in 
its 4-byte field, that represents the sequential position of the block or record, relative to 
the beginning of the direct access file or partition. The number of the first record of a file 
or partition is 1. 


*The absolute disk identification address, an ID used in other data management systems, is a 5-byte address containing the 
cylinder number, the head number, and the record number that define the physical location of a record on a disk. In OS/3 
data management, all disk record addressing in direct access files is relative and uses a 4-byte address in either of the 
formats described here. OS/3 ISAM uses a 5-byte file-relative address (or record pointer); refer to Sections 10 and 17. 


Ce, 
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By relative track address, understand a 4-byte hexadecimal number, the first three bytes. of 
which represent the track number on which the record or block is written, relative to the 
first track of records in the direct access file-or partition. Track number begins with 001. 
The fourth. byte of the relative track address represents the sequential number of the block 
or record on this relative track; ae or record numbering begins with 1. 


For example, to eae te record 7 on-relative track 143 in a direct. access file, if you have 


specified RELATIVE=T in your DTF, this is what you would move. into the 4-byte field in 
your program: 


Ly record 7o0n | 


relative track 143 


Assume, that this same file is laid out with eight blocks to a track, but that you have 
‘specified RELATIVE=R in the DTF. The same record would be the 1143rd in the file, and 
you would specify its relative disk address this way in the 4- ‘byte field: 


Byte: 0 4 2 3 





——- relative record 1143 


Any relative disk addresses that you generate in your program for. use with the data 
management imperative macros designed for random processing must be presented to 
data management in the appropriate one of these two forms, and you must inform data 
management as to which form to expect by specifying the RELATIVE keyword parameter. 


You may, at this point, be asking yourself when a relative disk address is the ID of a block, 
and when it is the ID of a record; you may also want to know how to decide between 
relative track or relative record addressing. These questions are taken up in the next few 


‘paragraphs, but a glance back at Figure 14—4 will suggest part of the answer: that a 


record has an ID only in the same sense that a record has a key. When it is in unblocked 
record format (fixed or variable in length), a record actually exists on disk in a block as 
shown in the figure, and the ID of the block and its key can both be considered to 
represent the only record in the block. | 
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For example, when you are referring to your direct access records by key, using the block- 
level READ,KEY imperative’ macro for retrieving data from your file, you specify to data 
management the key of the block that contains the record or records you are after, placing 
it in the KEYARG field of: your .program (15.6.13). You: must also ‘specify a relative disk 
address to indicate to data management where in the file to start its Search for the desired 
block, by moving it into the SEEKADR field of your program (15.6.24). This then, is the ID 
of the first block to be tested for a key that matches the content of your KEYARG field. You 
should consider it the ID of a record only if this record is in the unblocked format and the 
only record in the block — which it must be in a DTFDA file. 


Moreover, if you want to save the ID of the block that the READ,KEY macro retrieves for 
you (to use it, for example, in later processing of the file — perhaps in another program), 
then you must specify the IDLOC keyword parameter in your DTF, thus providing the label 
of a field to which data management makes.a return: the relative disk address of the keyed 
block it has just retrieved. This is discussed further under. the IDLOC keyword parameter 
(15.6.7), where Table 15—5 summarizes the ID returns made after execution of the 
various forms of the READ and WRITE imperative macros. Once the READ,KEY macro has 
read the block you want into main storage, you may access the desired record by your own 
deblocking code or by successive issues of the GET macro. For further details, refer to the 
READ,KEY macro description, 15.7.14.2. 


When you are e retrieving data fone, your file with the READ,ID imperative macro, you must 
specify the ID of the record you want retrieved by placing this, in the form you have 
specified with the RELATIVE keyword parameter, in the field defined by your SEEKADR 
keyword. Although data management reads in the entire block, including the key if the 
block has one, it points to the specified record by loading its displacement within the block 
in a field of your DTF designated as filenameD. The ID returned by data managemeni to 
the IDLOC field of your program after the successful execution of the READ,ID macro is 
the relative disk address of the b/ock that is physically the next in your file. Again, this ID 
is in the form you have specified with the RELATIVE keyword parameter; further details 
are documented under the READ,ID macro description, 15.7.14.1. 


The advantage of specifying the re/ative track form of record addressing in DTFDA files 
(RELATIVE=T) is that you can treat each track of your data as if it were a partition or a 
subfile (only DTFNI files may actually comprise partitions or subfiles (15.4, 15.5.3)). On the 
other hand, such use requires that you keep tight control over your data, knowing what 
goes where in each case, without the help of the DTFNI and DPCA file tables or the 
special imperative macros (NOTE, POINT, COIN: SETP, and SETS) that cannot be issued 
to cies files: 


An advantage of specifying relative record addressing (RELATIVE= =R) is that you.can stand 
off further removed from your file, without as much concern for its layout on disk, 
remaining independent. of all actual disk locations. 


The RELATIVE keyword is not specified for the DPCA declarative macro; when you are 
randomly processing a partition of a DTFNI file, data management uses the specification of 
the RELATIVE keyword you made in the DTFNI macro defining the file to which the 
partition belongs. 


ptt 
— 
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Reyer Parameter RELATIVE: 


For DTFDA flies wed fandonly processed files defined by the DTENI macro, eaacties 
the method of relative addressing. Not: used for DTFSD files. For direct access: file 
partitions, data management uses the specification in the DTFNI macro; the RELATIVE 
keyword is therefore not specifiable in the DPCA macro. 


RELATIVE= R . 
Specifies relative record addressing, | in the form: 


rrrr 
‘where: 


rrr. . . a ; 
Is a hexadecimal number, right-justified in a 4-byte field, that 
represents the number of the block or record to be accessed, relative to 
the first block or record in the file or partition. The numnpel of the first 
block or record in a file or partition is 1. 


| RELATIVE=T 
Specifies re/ative track addressing, in the ake 


tttr 
where: 

ttt — 

Is a.3-byte hexadecimal number, relative to the first track in the file or 


‘partition, of the block on which the record. or: block occurs. Track 
nummeer tng begins with 001. : pate 


Is: the Seauertial number. of the Bee or “block on this relative track: 
record numbering. begins with 1. 


15. 6. 23. Specifying a Save Area for Contents of General Registers [SAW ARES) 


Before you issue an imperative macro for srocessind any 0S/3 data management file, ai 
should generally first load general register 13 with the address of a 72-byte labeled save 
area — always aligned to a full-word boundary — in which data management will expect 
to save the contents of your registers. One purpose of the SAVAREA keyword parameter.is. 
to make things easier for you if you are.converting a program, written for use under some 
other data management system, in which you have already used register 13 for some 
other purpose. 
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When you are converting such a program to run under OS/3 data management, you need 
not recode it to revise your use of register 13. You need only add to it a 72-byte labeled 
save area, aligned as described, and specify its address with the SAVAREA keyword 
parameter in the DTF for each file your program will process. (Although you will need to 
‘specify this keyword in each DTF, you need only one register save area for your program.) 


In writing a new program using OS/3 data management, you must make one choice or 
the other: load register 13 with the same area address before issuing macros, or specify 
the SAVAREA keyword. One advantage of using the SAVAREA keyword is that register 13 
then becomes available (along with register 2 through 12) for use in your program: as the 
IOREG or VARBLD register, for example. 


When it does not encounter the SAVAREA keyword in your DTF, data management will 
always assume that, before issuing an imperative macro to the file, you have preloaded 
register 13 with the address of a 72-byte save area, aligned on a full-word boundary. 


Keyword Parameter SAVAREA: 


SAVAREA=symbol 
Specifies the address of a 72-byte labeled save area for the contents of general 
registers, full-word aligned, where symbol (label) is the address. If used, must be 
specified in the DTF for each file your program will process; however, only one 
such save area is required per program. Not supported by DPCA declarative 
macro, as SAVAREA is a file-level parameter. 


15.6.24. Specifying Relative Disk Address for Random Processing (SEEKADR) 


The SEEKADR keyword parameter is mandatory for random processing; you must specify it 
for DTFDA files and for randomly processed files defined by the DTFNI declarative macro. 
Its purpose is to specify the 4-byte field in your program into which you load the relative 
disk address you will use for directly accessing a block or updating it, for initiating a key 
search, and for controlling the movement of the disk head. There are therefore three basic 
ways you must use the SEEKADR keyword parameter: with the READ,ID and WRITE,ID 
macros; with the READ,KEY and WRITE,KEY macros; and with the CNTRL and 
WRITE,RZERO/WRITE,AFTER macros. 


When you are issuing. READ,ID and WRITE,ID macros to directly access blocks in a 
randomly processed file to retrieve and update them, you must load into the SEEKADR 
noe of your program the relative disk adarees (ID) of the current block. 


On the other hand, when you .are raterancitid your keyed blocks by key and therefore 
using the READ,KEY and WRITE,KEY macros, the address you must load into the 
SEEKADR field is the relative disk address at which data management is to start the key 
search. | 


fr, 


I, 
ae 
- 4 
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The third required use of the SEEKADR keyword parameter is related to your uses of the 
WRITE,RZERO macro and the CNTRL macro. When you use the WRITE,RZERO and 
WRITE,AFTER macros to select and initialize a disk track, you must load, into the 
SEEKADR field of your program, the relative disk address to which data management is to 
reposition your output file for subsequent processing, initialized so as to write the first 
block on. the new track. with the WRITE,AFTER macro (15.7.11.2). Similarly, when you use 
the CNTRL macro to control disk head movement (either to return to the current track or to 
seek another track, 15.7.15), you must place the relative track address you want in the 
field specified by the SEEKADR Roy aord persivetel: 


In certain circumstances (for example, when you want to use the ID returned by the 
WAITF macro that follows each READ or WRITE macro issued to automatically update the 
SEEKADR field for you), you may specify that the. IDLOC and SEEKADR fields are 
physically one and the same area in main storage. Refer to 15.6. 7, where the means and 
rationale for doing so are discussed in some detail. 


Data management does not require a special alignment of the IDLOC or SEEKADR field (as 
it does for the |/O buffer and certain other areas). However, you may well :need to align 
the SEEKADR field on a specific boundary if you are performing certain operations on it. 
For example, if you are controlling movement through your file by incrementing the 
relative track number (having specified RELATIVE=T), using, say: an add immediate (Al) 
instruction, you should align the 4-byte SEEKADR field on an odd boundary so that the 
increment is added to byte 2 by this half-word-oriented instruction. 


Consider the following example, which presupposes relative track addressing in a direct 
access file named DAMEFLE. You are stepping through the file, updating blocks on every 
third track. This is the content of your IDLOC field at a certain point, representing record 7 
on relative track 145: 


Byte: 0 1 2 3 
t. t t r 


olololtlotgyti1{oy7 


You have aligned your SEEKADR field (the label of which is SKADR) and defined it as a 4- 
byte constant. with the following pair of BAL statements in your program, and you are 
moving the IDLOC contents to this field before each incrementation. 


LABEL nei OPERAND A 
16 


ucrenspat be T leu 3) Xxx! 
| ‘scape... [be leca" 0.000! 


1. Assuming that the alignment of previously defined storage areas leaves the 
location counter at an even boundary, this statement forces odd alignment. No 
label is required, of course, except to document the point. 
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2. _ The label SKADR (which you have equated to the SEEKADR keyword parameter 
in the DTF defining the direct access. file’ ak taae is defined as a 4- oe 
character inet full- wor) constant. 


At he: appropriate point in: your exepurabie: code, you issue the following pair of 
instructions, to increment relative track: number by ‘2 and to write record 7 on relative 


track 147. 


LABEL AOPERATIONA OPERAND A 
1 10 16 . 


TNCREM,, | AZ... | SkADR+I>2,. 
fannie Maitre PANE LE. ID, 
in ey eles 


The half word addressed by the Al instruction comprises bytes 1 and 2 of the 
_ -SEEKADR field, SKADR. Byte 2 contains the least SIGHINCE TE byte of the eIaLVe track 
number, ttt. 


Other-c operations; may require other alignment - — but whatever you do to the contents 
- of the SEEKADR field, remember that they must be in fixed- “point binary format pelore 
you issue an imperative macro that uses the seek address: 


~ WRITE,RZERO-~ 
-WRITE,ID. 

READ, ID 

READ,KEY 

CNTRL 


Remember also that the relative disk address must never have a negative or zero 
value. cs 


Before leaving the subject of relative track addressing, you should note that, when your 
DTFDA file contains optional user labels, data management reserves the entire first track 
on the first volume of your file for them. However, you must not include this user label 
track in your relative track count. The first of your data blocks is written on the first track 
after the label track, and this, then, is relative track 001. 


The same caution applies also to the DTFNI file containing user labels, but these files may 
also contain subfiles in each partition. When this is the case, data management reserves 
the first track after the user label track (or the first track of the file, in the absence of user 
labels) to maintain its subfile tables. Relative track 001, on which the first of your data 
lies, may then be bhai the third track of the extent, it is Sul the first nate track of your 


file. 


oe, 
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There are two reasons for keeping these points in mind. One is that, when you are using 
the system utility (SU) symbiont to obtain a print of a specific part of your disk file, and are 
specifying: certain heads and cylinders to be listed, you must include the user label and 
subfile table tracks in your reckoning. There: is no way to specify a re/ative track to. the SU 
symbiont (which is documented in the system service program (SSF) 4 user guide, UP- 8062 
(current version)). 


Another reason to remember the user label and subfile table tracks in your calculations is 
that the length of these tracks (in terms of the number of your data blocks-they could 
contain if used for data) is included by data management in its calculation of the current 
relative block and certain other relative addresses that it maintains in the DTF file tables. 
You will eventually learn to read these fields in the DTF you see in a program dump, for 
‘they are often’useful in debugging, and you will need to be prepared for an otherwise 
mystifying discrepancy. For example, if each track in your data file can hold 10 blocks — 
and you have both user labels and subfile tables on disk — each relative block address 
contained in the DTF will appear to have been inflated, being 20 blocks higher than you 
expected. 


The form in which you load the relative disc address into the SEEKADR field is governed 
by. your specification of the RELATIVE keyword parameter; see 15.6.22, where relative 
track and_ Telative record addressing are discussed in detail. In no case may the ID be 
negative or zero. 


Keyword Parameter SEEKADR: 


SEEKADR=symbol 
Specifies the location in your program into which you load the relative disk 
address for use in processing direct access files with the READ,ID; READ,KEY; 
WRITE,ID; WRITE,RZERO; and:CNTRL-imperative macros. Required for DTFDA 
files and randomly processed files defined by the DTFNI macro. Form in which 
address is loaded is governed by your specification of the RELATIVE keyword 
parameter. Relative disk address may not be negative or zero. 


15. 6. 25. Resa Initial Disc Soe: to a File Partition (SIZE) 


When you are defining each Section Si a DTFNI file, you may Seexity the percentage of 
the total file allocation that data Management is to penilauy assign to the aeons by 
using the SIZE keyword ay : 


You ‘heieate the initial disk space you require for bach sairittion by specifying me SIZE 
keyword parameter in the a or DPCA declarative macro. 


It is not necessary to specify the SIZE heynord parameter in the DTFNI or DPCA macros if 
you want only 1% of the total file allocation to be assigned initially to the first partition and 
to those partitions that you do not specify other percentages for. 
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As you know, you specify the tota/ file space allocation to OS/3 job control when you 
initially allocate the file, using the fourth and fifth positional parameters on the EXT job 

-control statement of your device assignment set. For subsequent automatic dynamic 
extension of a partition, you. will use the UOS keyword paramere! a 6. 30)... 


Se Paraiieter SIZE: 


SIZE=n 
Specifies the percentage of total file allocation to be initially assigned by data 
management to the partition being defined by. this. DTFNI or DPCA declarative 
macro. Not used with nonpartitioned DTFNI files, nor with DTFSD or DTFDA files. 


If omitted: from DTFNI macro, data management assumes. that SIZE=1 had been 
specified and assigns 1 percent. If omitted from DPCA macro, data management 
makes a 1 percent allocation. 


15.6.26. Extending Key Search to Multiple Track (SRCHM) 


- When you issue a READ,KEY imperative macro to a DTFDA or randomly processed DTFNI 
file, the search continues until the first block headed by a key that matches the content of 
your KEYARG field is found, or the end of the current track is reached, ‘whichever occurs 
first. To search beyond the end of the current track to the end of the cylinder, you may 
specify the SRCHM keyword parameter in the DTF. 


Keyword Parameter SRCHM: 


SRCHM=YES 
“Specifies that a search Rsk cena to a DTFDA or andorly aon DTFNI file 
“(READ,KEY) is to be extended beyond the current track to the end of the cylinder. 


15.6.27. Specifying Support of Subfiles in a Partition (SUBFILE) — 


You may further subdivide each of the seven optional partitions of a DTFNI file into as 
many as 71 subfiles. These subfiles, which you: will: access serially for processing within 
the partition, via the SETS imperative macro (15.7.5), maintain the same characteristics as 
the partition. (You select the appropriate partition with the SETP macro (15.7.4).) 


Data management reserves one track of the first volume of the file on which to maintain 
subfile tables when subfiles are to be supported; to indicate to data management that it is 
to do so, you must specify the SUBFILE keyword parameter in the declarative macro that 
defines each separate partition containing subfiles: the DTFNI macro for the first partition, 
and the appropriate DPCA macros for the sueseedlng pariien®. 


‘If you file does not contain optional user labels, data management writes the Zubfile tables 

on the first track; when you do have UHL/UTL, data management writes these on the first 
track, and the subfile tables go on the second track. Refer to 15.6.24 for a discussion of 
the effect the presence of these tracks have on positioning yourself in your file. Refer to 
15.7.5 for discussion of the contents of the subfile. 


Ce 
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we Parameter SUBFILE: 


SUBFILE=YES : | 
Specifies that data management is to support subfiles in the partition datinee by 
this DTFNI or DPCA declarative macro. A maximum of 71 subfiles may be 
established in each’ partiton; you access these serially by issuing a: SETS 
imperative macro to the file, having previously selected the correct bparinon with 
a SETP imperative macro. 


15.6.28. Specifying Processing of User Trailer Labels (TRLBL) 


As you recall, you may have optional standard. user trailer labels (UTLs) in your nonindexed 
disk files. These are processed by your label routine (LABADDR keyword parameter, 
15.6.15) and written by data management on the user label track when you issue the 
CLOSE imperative macro to the file. When you want to process your UTL on closing the 
file, you must specify the TRLBL keyword. parameter beforehand in the DTF for the file; 
naturally, you’: must also provide: data management with the address of: your label 
processing routine ‘by specifying the LABADDR keyword parameter. If you omit the TRLBL 
keyword parameter, your LABADDR routine does not receive control at file close, and your 
UTLs, consequently, are never processed 


cey wierd Parameter TR LB e 


TRLBL=YES : 
Specifies that you will process UTL when you issue the CLOSE fupereiiva macro 
to the DTFSD, DTFDA, or DTFNI file defined by this DTF. You must also specify 
the LABADDR keyword parameter. 


15. 6. 29. Detining t the Type of File (TYPEFLE) 


One of the most significant keyword parameters, used for DTFSD, DTFDA, and DTFNI files, 
is the TYPEFLE keyword parameter. It is important to you because with it you specify not 
only what type of optional header/trailer /abe/ processing you will perform on the file, but 
also what basic processing you will be performing on the data itself. It is also important to 
note that, having defined a file for one mode of processing, you are generally restricted to 
that mode until you explicitly os fora change in one of the ways pointed out in the 
following discussion. : 


This is ine format ‘Gi the TYPEFLE Sree parameter: 


TYPEFLE= Sivr| 
INOUT 





If you omit specifying this keyword, data management assumes that TYPEFLE=INPUT has 
been specified. 
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The effect of the TYPEFLE keyword on header/trailer label processing: is simply 
summarized: TYPEFLE=INPUT specifies that data management will read header/trailer 
labels for the file;s TYPEFLE=OUTPUT specifies that it will write header/trailer labels. In 
both cases,.these actions include reading, checking, and writing your optional UHL and 
UTL, which you generate and update with your LABADDR label processing routine. If you 
specify TYPEFLE=INPUT and. the LABADDR and ,FRLBL keyword parameters, data 
management .assumes UHL and. UTL. exist. You may not specify TYPEFLE=INOUT for 
DTFDA files, but this specification for DTFSD or DTFNI files is what you use for label 
updating. 


The TYPEFLE keyword parameter controls. only. the mode of /abe/ processing to be 
performed. on files defined by the DTFDA macro; for DTFSD files and sequentially 
processed DTFNI files; however, it also constrains your processing of the data:records in 
the file. When you specify TYPEFLE=INPUT for one of these, you define a file that is to be 
read only. You. may. not issue an output function to it (that is, the. PUT imperative macro) 
unless you have a/so specified UPDATE=YES in the DTF. (The UPDATE keyword parameter 
is described in 15.6.31.) Similarly, when you. specify. TYPEFLE=OUTPUT, you define a file 
that is to be written,.and you may not issue an input function (the GET. imperative macro) 
to the file. Specifying TYPEFLE=INOUT defines a file that you: may use. Sier as an: enue 
or an output file; issuing the GET or PUT macro as pis ibwas ae 


After you have used a file as an output type, you must close the file and ene its ‘ype to 
input before you reopen it. You alter the file type by issuing the SETF imperative macro to 
the file; this procedure is developed in 15.7.8. (The OPEN macro is deschibed in Ve: 7. 1; the 
Coote mpereie. in 1S. 7. 2.) z 


wou Parsineter: TYPEFLE: 





Specifies a read-only file; used with DTFSD, DTFDA, and DTFNI macros. Data 
management will read and check standard labelsfor this file. You may not issue 
an output function to this file unless you have also specified UPDATE=YES in the 

-DTF. Data management assumes you have epee TYPEFLE=(NPUT when you 
omit me ee pleats Levene 


_TYPEFLE=OUTPUT. ak aa ; 

~ Specifies a: file that is to be written;. eee with te DTFSD, DTFDA, and DTFNI 

. macros. Data: management will Write standard labels for this file. For DTFDA 
files, this keyword controls only the mode of /abe/ processing ‘to be employed; for 
DTFSD files and sequentially processed DTFNI files, it also controls the mode of 
record processing you may wse'‘within the file. You may not issue an input 
function to this file unless you close it, reset its file processing direction to /nput 
with the SETF imperative macro, and reopen the file. 


TYPEFLE=!INOUT ‘ 
Specifies a file that you may use for either input or r output. Used with Binoy ane 
DTFNI files; not used with DTFDA files. : ; 


a 
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_15.6.30. Specifying Dynantic: Extension of a File Partition (UOS) 


You use the SIZE keyword caraimeies (15. 6. 25) to assign ‘initial disc space fo é a 5 paRIION of 


_a DTFNI file, but when you anticipate a need to.extend a partition dynamically, you use the 


UOS keyword parameter. This keyword is specified:only with the DPCA macro or with a 
DTFNI macro which defines the first (or only) partition of a nonindexed file. 


With the UOS keyword, you specify to data management what percentage of ,your 


secondary allocation of disk space to the file it is to suballocate each time the partition 
requires additional space. From your acquaintance with OS/3 job control, recall that you 
specify the number of cylinders or blocks that is to constitute the secondary allocation of 


_disk space to. a file with the third positional parameter on the EXT job control statement of 
your file's device assignment set. (To review this. statement in detail, you should refer to 


the job control user guide, UP-8065 (current version).) . 


When. you have specified the UOS keyword parameter for the partition (and. have not 


“specified a zero increment in your EXT. job control statement), and the partition requires 


more space, data management.-will automatically suballocate to it the number of additional 


tracks that is equivalent to the amount. of storage.specified: by the UOS keyword. This 


amount is designated the unit of store; the:same amount is used each time the partition 


needs extension. Data management keeps. a record of suballocation information neevelopee 
for all partitions in.the format 2. label: associated , with the file (Appendix D). . 


Data management. learns of the need to ‘tend a file Sartiton each time one of your ‘auipil 
imperative macros (PUT or WRITE) references a block that lies beyond the current 
maximum relative block address data management maintains in the PCA table for the 
partition. Data management acts automatically to extend the partition, but there are 
several points you should keep in mind. 


One point is that.you.must have specified the UOS keyword parameter i in the first place: if 
you omit it, no extension can be made. A second point.is that file partitions will not be 
extended beyond the volumes on. which the file resides. Furthermore, if, after extending 
your partition by, one unit of. store, data management finds that the requested block still 
lies beyond the new maximum relative block address, it sets the invalid /D flag (byte O, bit 


1).in filenameC and transfers control to.your error routine.(or to you inline if you have no 


error routine). Data management takes the same action if there is no space available on 
the disk to extend the partition or if you have not specified the UOS keyword. Finally, a 
unit of store specification greater than 100% is not valid. 


Keyword Parameter UOS: 


UOS=n 
Specifies, as the unit of store, The personage of. secondary disk storage 
allocation for the file that data management is to suballocate to the partition 
_ being defined each time it requires more space. The value of n, which is the 
specified percentage, may. not exceed 100. Secondary storage allocation is 
specified in the EXT job control statement in the device assignment set for the 
 _ file.. = Sate ae | 
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Used with DPCA. declarative macro or with DTFNI macro defining first (or only) (> 
pene of a nonindexed file. Not used with Peer or DTFSD macro. | ~ 


Af oiniited: or ‘if a: zero. nes storage allocation is specified i in EXT job control 
_ statement, no extension will be made. ~ 


15.6.31. Specifying Update Processing Mode for Seaueone Files (UPDATE) 
The UPDATE keyword parameters is used with the DTESD and DTFNI macros. 


You will recall from the discussion of the TYPEFLE keyword parameter that when you have 
specified TYPEFLE=INPUT, you define a read-only file and may not issue an output 
imperative macro to it unless you have also specified UPDATE=YES (15.6.29).° 


When, therefore, you have an input file defined by a DTFSD macro, or an input file defined 
by the DTFNI macro that is to be processed sequentially and you want to update your data 
records, you specify UPDATE=YES to make this possible. Only then may you retrieve your 
records with the GET imperative macro and, modifying them if you need to, rewrite them 
to disc with the PUT macro. (The UPDATE=YES specification is also accepted in your DTF 
for sequentially processed files you have defined as TYPEFLE=INOUT, although you do not 
need to use it for this 2-way type of file.) Another point worth remembering is that the 
UPDATE keyword parameter, unlike the TYPEFLE keyword, has nothing to do with your 
mode of label processing; its use: affects ony on moee of oat Reece processing in 
sequential np UY, files. — 


ast 


Keyword Parameter UPDATE: 


UPDATE=YES 
Used only with DTFSD > macro’ or DTFNI macro defining, sequentially processed 
files and only when you have specified TYPEFLE=INPUT or TYPEFLE=INOUT for 
these files. When used, ‘specifies that sequential output function (PUT macro) 
may be issued to update data records in file. Unrelated to label processing. 


If omitted fen DIF for a sequentially processed input file’ (TYPEFLE=INPUT), you may 
not issue an output function to the file. 


15.6.32. Specifying Register for Residual Space, Variable Records (VARBLD) 


When you are outputting variable-length, blocked records to a sequentially processed disk 
file, and you are building these in an I/O area payions a work area, you must specify the 
VARBLD keyword parameter. 


Data management uses the general register you specify with this keyword to inform you of 
the number of bytes of residual space remaining in the |/O area after the execution of 
each PUT macroinstruction you issue. Before you issue your next PUT macro, you must 
test whether there is enough space left to accommodate the next record. If there is not, 
you must issue a TRUNC macro to write out the current block. (These procedures are f 
detailed in 15.7.9.4 and 15.7.10.) ae 
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The VARBLD keyword parameter is not supported by the DTFDA macro: because the 
blocked record formats may not be specified for DTFDA files; you may specify the keyword 
for sequentially ees output files or partitions defined by the DTFSD, DTFNI, or DPCA 
declarative macros. 


Keyword Parameter VARBLD: 


VARBLD=(r) 3 
Specifies a general register into which data management pace the uinber: ‘st 
bytes remaining in the 1/O area after each execution of a PUT macroinstruction 
to a sequentially processed output file containing blocked, variable-length 
records, where ris the number of the register and must be enclosed in 
parentheses. Supported for DTFSD, DTFNI, and DPCA macros; not supported for 
DTFDA macro. Value of r may range from 2 through 12, but register 13 may also 
be used if SAVAREA keyword has also been specified. 


When you are building variable-length blocked records in an I/O area for output to a 
sequentially processed file, without a work area, you must access the VARBLD register to 
test whether enough space remains in the area for the next record before issuing your 
next PUT macro. You issue a TRUNC macro when it does not. See 15.7.9.4 and 15.7.10. 


15.6.33. Specifying Parity Check Verification of Output (VERIFY) 


When you want data management to make a parity check of your data records or blocks 


after it has written each of them to disk, you must specify the optional VERIFY keyword 
parameter. Verification necessarily increases execution time for the output commands 
involved (PUT or WRITE macroinstruction). If.a parity check is conducted and reveals an 
error, data management normally sets the output parity check error flag (byte 2, bit 2) in 
filenameC and transfers control to your error routine, if you have SDECMIEe one, or to you 
inline yAppenals B). 


You may specify ne: VERIFY keyword parameter with the DTFSD, -DTFDA, and DTFNI 
macros; it is not supported by the DPCA macro. 


Keyword Parameter VERIFY: 


VERIFY=YES 
Specifies that data management is to conduct a parity check of output blocks or 
records after writing them to disk. Parity check verification necessarily increases 
execution time for PUT or WRITE macro. Optional for DTFSD, DEED. and DTFNI 
files; not supported for DPCA macro. 


If omitted, no verification is performed; however, data management may detect an 
output parity check error by other means. You may direct data management to take 
certain actions with the ERROPT keyword parameter (15.6.5). 
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15. 6. on. peel al medvential processing: ina VOU Area WVORIAL 


When you are. going to process. input or output records: sequentially in a work area rather 
than in the I/O area, you indicate this to data management by specifying the WORKA 
keyword parameter in the DTF. This keyword is supported for the DTFSD declarative macro 
and for sequentially processed files or partitions defined by the DTFSD declarative macro 
and for sequentially processed files or partitions defined by the DTFNI or DPCA macro; it is 
not specified for the DTFDA macro. 


You: epecity se medrese of the work area in the’ dedond positional parameter of each PUT 
or GET macro you issue to the file (15.7.9 and’ 15.7.12). When you use a work area and 
therefore specify the WORKA > keyword, you must not specify the IOREG keyword 
parameter in year DTF (15.6. EN 


Keyword Parameter WORKA: 


One nn on oe ae 
Specifies to data management that you will be processing input: or output records 
~ sequentially ina work area and not in the I/O area. Supported for DTFSD macro 
and sequentially processed files or partitions defined by DTFNI or DPCA macros; 
not supported for DTFDA files. 


Do not specify IOREG keyword: parameter. when you specify the WORKA keyword: » 


aoe work area is a with a ae of GET and PUT macro. 


15. 6. 35. “Specifying peste of WRITE, ID Macro “WRITEID) 


When you. are processing a DTFDA fite or r-randomly- processing a DTFNI file and will issue 
the WRITE,ID form of the WRITE imperative macro to locate an output block by:means of 
its relative disk address or ID, you must notify data management by specifying the 
WRITEID keyword parameter in your DTF. ied use of the WRITE macro is. "detailed in 
15.7.11.4.) 


Keyword Parameter WRITEID: 


WRITEID-YES 
Specifies that you will issue a WRITE,ID macro to the randomly siicbacead file 
defined by this DTFDA or DTFNI declarative macro to locate an output block by its 
relative disk address (ID). Not supported for DTFSD files. See ee. 7. 41 .4 for the 
WRITE,ID macro. 
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15.6.36.. Specifying Issue of WRITE,KEY Macro (WRITEKEY) | 


When you are processing a DTFDA file or randomly processing a DTFNI file and will issue 
- the WRITE,KEY. form of the WRITE imperative macro to rewrite or update a ‘block just read 
by the READ,KEY macro, you must notify data management by specifying the WRITEKEY 
- keyword parameter in your DTF. (These uses of the WRITE and READ macros are detailed 
in 15.7.11.5 and 18.7.14.2.) 


- Keyword Parameter WRITEKEY: 


_ WRITEKEY=YES | 
Specifies that you will issue a WRITE, KEY imperative macro to “the randomly 
processed file defined by this DTFDA or DTFNI declarative macro to rewrite a 
block just retrieved by the READ, KEY macro. Not supported for DTFSD files. See 
15. ni 11. 5 tor the WRITE, KEY macro; 15.7.14.2 for the READ, KEY macro. 


| 15. 6. 37. " Nonstandard Forms of the Keyword Parameters. | 


In order to minimize any recoding you may need to revise programs previously prepared to 

-run under other data management systems, OS/3 data management accepts certain 
variant. spellings for the keyword parameters described in this section. The nonstandard. 
forms of these keywords, listed alphabetically, are as follows: 


aa haa: <<NSnatantard. < OS73: °: Nonstandard ~ OS/3 _ 
ee Spelling - Standard Form | Spelling | Standard Form — 
AFTR Ss AFTER =——s|—s RID READID 
BKSZ—sCBLKSIZE. ~——S*|| RDKY. =——S—S—SsS#READKEY 
‘EOFA =—~—SREOFADDR REL RELATIVE. 
-ERRO  =———EERROPT | SKAD SEEKADR 
IOA1 ~~ IOAREA1 SRCM SRCHM 
IOA2 ~ 1OAREA2 TYPF —TYPEFLE © 
loRG =—~=CS~SREG—C“‘=*C~*‘*YS:=CPDTT UPDATE 
KARG KEYARG VBLD VARBLD 
KLEN ~ KEYLEN ~~. +| VRFY | VERIFY 
LBAD=——~*=«SABADR.~—S*dYWWRID.——SsS(WWRRITEID 
~RCFM  RECFORM WRKY — - WRITEKEY 
a RCSZ RECSIZE WORK WORKA 


Table 15—7 summarizes nonindexed file declarative macro keyword parameters. 


eee 
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Table 15—7. Summary of All Declarative Macro Keyword Parameters Used With the Nonindexed File Processor System (Part 1 of 2) 


Declarative Macros 


Keyword Keyword 


‘Parameter Specification Used.to Specify or = 


DT | DTFSD | DTFDA | | pTFNt | DPCA 


ACCESS . This DTF: read/update/add use. 
Other jobs: no access 


This DTF: read/update/add use 
Other jobs: read use 





This DTF: read use 


Other jobs: read/update/add use 


This DTF: read use. 
Other jobs: read use 


[seawnrearrnerenaromee 


Bypass input record or ignore eee record despite 
parity error ; 


Address of user error routine 
Define field for next ‘austlable record address 
R Address of primary |/O buffer 


Specifies that file lock is not to be set on a lockable file 
at OPEN 


TP eecrione 


Format of data records 










ERROPT IGNORE 







IOREG 


KEYLEN 


LACE 


LOCK 


OPTION 


READID 


READKEY YES 










RECFORM 


RECSIZE 


x 
FIXBLK Xx 
VARBLK x 


RELATIVE Relative addressing method 


Ea _ ArRa 


SUBSEA 

















he ee 


GOO, 


Stes. 
es 
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Table 15—7. Summary of All Declarative Macro Keyword Parameters Used With the Nonindexed File Processor System (Part 2 of 2) 

















Declarative Macros 


DTFSD DTFDA DTFNI 























Keyword 
Parameter 


Keyword 


Specification Used to Specify or define 


[otf Address of register save area 
ae Address of seek address field 









SAVAREA 


assigned to partition 
i 


Define file type and mode of label processing 


Secondary allocation ONS a 
Update of sequential input file 
Count of residua! 1/O buffer space for VARBLK file 


_ Read/check of output records to be performed 
x Sequential processing in work area 























WORKA 
WRITEID 


WRITEKEY 


issue of WRITE, 1D macro 


a issue of WRITE, KEY macro : 2 





LEGEND: 
x Optional 
Required 


Not supported 
Assumed specification if keyword not specified. 


a 
hobo nou 





15.7. IMPERATIVE MACROS FOR NONINDEXED DISK FILES 


You inform the nonindexed file processor system of the distinct operations that data 
management is to perform on your files and partitions by including the appropriate file 
processing imperative macroinstructions in your program. 


There are 18 of these imperative macros available to you for processing your nonindexed : 
files and partitions; JTable ‘15—8 summarizes their functions. 


The paragraphs following the table describe the imperative macros in detail; the macro | 
descriptions are arranged in four groups, according to the file processing functions — 
involved: 


| Initialization and Termination Macros: 


OPEN 


CLOSE 
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LBRET 
~SETP - 
SETS 
POINTS 
FEOV 
-SETF | | 
- Creation, Addition, and Updating Macros: 
PUT 
TRUNC 
6 WRITE 
= Retrieval Macros: 
| ...GET. 
-RELSE 
READ 
= =§=Validation and Positioning Macros: 
CNTRL 
WAITF 
NOTE. ., 


POINT 


_ Before. issuing an imperative macro to an OS/3 data management file, you must provide, a. 
72-byte save area, full-word aligned, into which data management expects. to place the — 


contents of your registers. You may load general register 13 in your program, or use the 
SAVAREA DTF keyword parameter to specify the address of the register save area. mee 
15. 6. 23. Zz 
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Table 15—8. Summary of Imperative Macroinstructions for Processing Nonindexed Disk Files 






















































vee 
May be issued to 
Secondary Remarks 
Operands* DTFSD DTFDA DTFNI 
Files Files Files 
a. ‘File or partition termination — 
Creating, retrieving, and updating standard « 
user header and trailer labels 
et te Select partition for subsequent processing 
SETS subfile-number fo | med . Select subfile or terminate current subfile creation 
POINTS i eS Initialize to first block of file or partition 
ETF ‘INPUT aan lad Tes meee ee a 
' OUTPUT: : 
UPDATE 
& 





RZERO 
AFTER 






workarea 


CNTRL ee aft 3s 





= Block-level retrieval by key 


roe 


“Wait on 1/O completion; required after READ or WRITE 


NOTE Access current relative block address 
POINT address-field Position file to relative block address in address-field 


*Except for the LBRET macro, filename is assumed for operand-1; operands listed are secondary. 
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OPEN = 6 woe cee seh | : C* 


15.7.1. Opening a Disk File (OPEN) 

| You will use the OPEN imperative macro to open a disk file defined by the appropriate DTF 3 
“macro instruction in order to initialize it (and its partitions, if any) before it may be 

~ accessed by the logical IOCS processor. The OPEN. macro instruction calls the apPropHale 

_ transient routines to: perform the following functions: 

= ~§= validating and completing the file or partition tables; 

. validating or es ‘system standard labels; and 

a reading or. writing user standard header lapel 

_If you define a DTENI file to ve more Piban one partition (by Scacitvine two or. more PCA 
keyword parameters and by coding the necessary DPCA declarative macros), you initialize 


all partitions by issuing an OPEN macro for the file. 


This is the format of the OPEN macro: 







A OPERATIONA OPERAND 





,...,tilename-n] 





| filename-1[ 


(1) 
1 


Positional Parameter Tp 
filename | . ne | 
Is the label of one or more corresponding DTF declarative macroinstructions in. 
your program. You may have as many as 16 files opened. 


(1) or 1 
Indicates that you awe preloaded register 1 with the address of the DTF filetable. 
(You use (1) or 1 as the operand only when you have a single DTF.) 


Py, 
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‘CLOSE 


15.7.2. Closing a Disk File (CLOSE) 


After. you. have completed your processing of a disk file, you must issue the CLOSE macro 
to check that all your |/O orders have actually been completed and to read or write the 
system standard and optional standard trailer labels: in other words,.to terminate the file. 
Once you have terminated a file with the CLOSE macro (which calls a transient routine to 
perform all of these functions), you cannot access it again unless you issue another OPEN 
macro. An important point to note is that you do not terminate file partitions separately; 
once you have done with all the partitions of a file you intend to process, you terminate 
operations. by issuing one CLOSE macro for the fi/e that ‘contains them. (For this | reason, 
the Panons name never Bepeats as an ppcieney oF Hie sania macro.) gi 


The ‘etna of the CLOSE macro is: 






OPERAND 





A OPERATIONA- 





filename- 1 AL. 


a 


.,filename-n] 





an 


The three basic ways to code the CLOSE macro involve the use of symbolic addresses in 
the operand. 


Positional Parameter 1: 


filename | 
Is the label of the DTF declarative macro. in “your program; there may be 1 or as 


many as 16 files named. 


(1) or 
eee that you have preloaded register 1 with the address of the DTF file 
table. You may use (1) or 1 when you have only one file to terminate. 


*ALL 
Specifies that all files currently open in the job step are to be closed. 
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-LBRET 


15.7.3. Processing Optional User Labels (LBRET) 


You will use the imperative macro‘LBRET in your label processing routine.(whose symbolic 
address is specified to data management via the: LABADDR keyword parameter of your 
DTF) to create, retrieve, or retrieve and-update optional user header or trailer labels. Note 
that LBRET is the only data management macro your label processing routine mays issue. 
The maximum Pyne of eacn nDe of label- yeu may process is- Stgut 


When \ your LABADDR routine receives. epnirok: data management will:have loaded general 
register 1 with the address of the |/O buffer for use.in processing input and output UHLs 
and UTLs. You must always use: register 1;:even though you may have specified only one 
buffer with the IOAREA1 keyword; it is not possible to use a work area for processing user 
labels. / 4 


Your LABADDR routine is accessed when the file is opened and again when it is closed; 
register O contains the EBCDIC alphabetic. character 0. in its least significant byte when the 
file is opened and the character F when it is closed. Your LABADDR routine should be 
coded to access register O and to process, your header labels when the register contains O 
and your trailer labels when it contains F. - 


Another point to remember is that user header /trailer labels, if you have them at all, are 
maintained at the file level only; data management does not maintain them at the partition 
level. (For this reason, inete is no gir eciss denon Pee in the neon declarative 
macro.) a 


The format of the LBRET macro is as follows: 


A OPERATION A OPERAND 





where: 


Does not write or read a label; returns control to your program at the next 
instruction after the OPEN or CLOSE macroinstruction. 


rey, 


ite 
ie 
GO 
4 
} 
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2 : os Hycnee ls al ete bat : : ; wip ee 
Writes a label to an output file or reads a label from an input file; then returns 
«control inline to your program : at the: next instruction ace the LBRET 2 
‘ee macroinstruction. : ; 
3 


: Writes Rack to disk the label just read and returns control: to your program inline 
: at the next instruction after the LBRET 3 macroinstruction. 
TYPEFLE=INOUT: must be specified in your DTF declarative macroinstruction, or the file 
processing BUECNON reset: for nopdate piocese|eg with the ial macroinstruction. 
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15.7.3.1. Creating Optional User Labels 


Your LABADDR label-creating routine delivers your. standard user header or trailer labels 
to data management one at a time, up to the maximum of eight. Data management will 
write each label to the disk file. If you have specified LBRET 2, it will return control to your 
label routine after each label has been written, until the eighth label has been written to 
disk. Then data. management will transfer control to you inline. If you are creating user 
labels, control returns to you at the instruction next after the OPEN macro call by which 
you initially opened the file for processing. If you are creating user trailer labels, of course, 
data management returns control to you inline at the instruction next after the CLOSE 
macro call by which you are terminating your processing of the file. (Remember that 
reading or writing optional user trailer labels is one of the functions performed by the 
CLOSE macro.) Remember also where labels are written: 


m = =§6©User header labels are written by the LBRET macro on the first track of each volume 
of a DTFSD file, and on the first track of the first volume of a DTFDA or DTFNI file. 
They are 80 bytes long; their simple format is shown in 14.2.4. 


a User trailer labels are written on the first track of each volume of a DTFSD file and on 
the first track of the first volume of a DTIFDA or DTFNI file, following your user header 
labels. Their format and content are similar to those of the user header label and are 
also shown in 14.2.4. 


When you have fewer than eight user labels of either type to create, you issue LBRET 1 
when you have created the last one. After it has written the last label to your disk file, 
data management will return control to your program at the instruction next inline after 
your OPEN macro call. 


arr, 
% 
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15.7.3.2. Retrieving or Updating User Labels 


If you need to retrieve your user labels for updating or other label processing, you will 
specify in the DTF the type of label processing you intend to perform (TYPEFLE=INPUT or 
TYPEFLE=INOUT), specify TRLBL=YES if you are going to process user trailer labels, 
specify the address of your label processing routine (LABADDR), and open the file with the 
OPEN imperative macro. (You do not use the UPDATE keyword parameter of the DTF; this 
is not related to label processing but affects data 1/0.) 


When ane file is. sapenda: data management will deliver your user header and trailer labels, 
one at a time, to your LABADDR routine either until all existing user labels have been 
passed to you, or until you specify that you need no more, by issuing LBRET ‘1. . 


Your label routine processes’ each label delivered by data management and then returns 
control to data management by issuing the LBRET r macro with iP 2, or 3 for the Positional 
parameter. ” 


If you want to terminate label processing short of the maximum (eight standard user labels 
of each type), you issue LBRET 1 when you need no more (this implies, of course, that you | 
keep track). Data management then transfers control to you inline, to the instruction next 
after your OPEN macro call. 


When you are processing all your labels (but not updating them), you issue LBRET 2. Data 
management will retrieve the next label and pass it to your LABADDR routine. It will. 
continue to do so until there are no more to process; then, after you have processed the 
last label, data management automatically transfers control to the next instruction after 
your OPEN macro call. 


When you are updating your user header and trailer labels, you issue LB®= © 3: Here, data 
management will update ine deta Aust read, waning the new label to disk in the ‘place of 
the old. 
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SETP 


15.7.4. __ Accessing a Selected File Partition (SETP) . 


When you open a multipartitioned DTFNI file for processing, the aniy one of i its. partitions 
that you may then access is PCA1, the partition defined in the DTF itself. All partitons of 
the file are initialized when you issue an OPEN macro for the file, but only partition 1 set. 
active; you cannot access any. partition other than this first one with the OPEN macro. 
alone. To select another partition. of the opened file, you need the SETP macro. 


The SETP macro acts to select. the.new partition, but.it is important to remember that it 
positions you. for. processing this. partition at its current position;. that is, at the next 
accessible block after the point at which you were last processing. If you want to begin at... 
some other point, you will need to issue additonal macros, for examples SETS (15.7.5), 
POINTS (15. 1. 6), or POINT (15.7.18). Js ? _ 
Once you have accessed a ‘partition with the SETP macro, all subsequent processing. 
continues on the selected partition until you issue another SETP macro, All other. 
imperative macros with which you may process within a partition (POINT, POINTS, SEIS, 
and NOTE) depend on you to select the proper perches before calling them. 


This is the format of ‘the SETP macro; ‘notice that it. is the only imperative n macro that may 
have a partition name in the operand. | efi ues Se tbe agate: hies ie Mp. 13 









_ AOPERATIONA ___OPERAND 


filename partition name a 
(1) ,5 (0) 
: 0 











Positional Parameter 1: 


filename 
Is the label of the DTFNI declarative macro that describes the already-opened file 
of which partition-name is part. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFNI file 
table. 


Os, 
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Positional Parameter 2: 


partition-name 
Is the label of the partition control appendage (PCA1—7) that denotes the 
partition you want to access. (This is, of course, the same thing as the label of 
the corresponding DPCA declarative macro for PCA2—7 and the label assigned. 
: .to the partition defined by PCA1 within the DTFNI macro.) . . 


(0) or om 7. 
Indicates that. you. have preloaded register, 0 with. the address of the partition 
‘table defined by the DTFNI V Reynard (PCA1—7) that describes the partition you. 
want to. access. | 


Each DTFNI file table maintains the address of the partition that is currently active; when 

you issue a SETP macro, data management modifies this current partition address to 
indicate which partition you have selected to be active for subsequent file accesses. (When 
you close the file, you have no further access to the file until you initialize it again. with a 
subsequent OPEN macro, which once more sets PCA1 active.) 


If you have specified an index register (via the |OREG keyword. parameter of your DTF), 
each SETP macro’you issue ‘will cause the index register to be loaded for the partition you 
are accessing. (During the opening | of a multipartitioned file, only the: nde register for 
PCA1 will have been loaded.) | ! 
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i, 
BS 


SETS maak 4, FU, Tavs S 


15.7.5. Processing Subfiles within a Partition (SETS) 


Within each partition of a DTFNI file, you may establish as many as 71 subfiles. Subfiles 
must be created sequentially, but you may access them at random for data retrieval. If you 
intend to use subfiles in the first partition (PCA1) of a DTFNI file, you speci‘) the SUBFILE 
keyword parameter in the DTF; data management reserves one. track of the first volume of 
the file for maintenance of a subfile table. Similarly, if you want subfiles supported for any 
of the subsequent partitions, you specify the SUBFILE keyword parameter in the DPCA 
declarative macros describing these partitions. a 


Once you have selected the’ ‘partition to be subdivided, the SETS imperative macro is the . 
one that provides you with the ability to create and subsequently | retrieve the data in the 
partition subfiles. This is its format: 






AOPERATIONA =} 


(filename) (subfile-no.) sete 
(1) (0) 
1 0 ee 


Seman 


OPERAND 





Positional Parameter 1: 
- filename 
Is the label of the DTFNI macroinstruction describing the file to which the 
subdivided partition belongs. 
(1) or 1 
Indicates that register 1 has been preloaded with the address of the DTF file 
table. 


Positional Parameter 2: 


subfile-no 
Is the decimal integer number of the subfile (1 through 71) to be referenced. 


(0) or O 
Indicates that register O has been preloaded with the subfile number. 
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The reason that the partition name does not appear in the operand is that the SETS macro 
expects that you have already selected the partition you want, by issuing an appropriate 
SETP macro before calling it. lf you have not done so, or if the SETP macro you issue is for 
the wrong file or partition, data management sets the /nvalid subfile bit (byte 3, bit 3) in 
the error flag field of the DTFNI file table, referenced as filenameC (Appendix B). You 
should check this bit whenever you issue a SETS macroinstruction. i 


What ine SETS macro does is to maintain a Sardtions: -relative subfile table, on. ‘the track of 
the first volume of the file that you reserved by specifying SUBFILE keyword. parameter in 
the DTFNI or DPCA macro. (This is either the first track on the volume or, when optional 
user labels are present, the first track after the user label track.) Data management uses 
this table to keep track of the start of each subfile: the address of the record that starts it. 
No. record is kept by data management of the end of a subfile; unless you keep track 
yourself of the record with which it ends, it is possible to process through a subfile to the 
end of the partition or logical EOF. 


The subfile table is not available for you to access, but you may examine it in a disk print 
taken with the system utility (SU) symbiont. To know its contents may help you visualize 
what the SETS macro is‘doing for you when you create or retrieve subfile records. There is 
one 6-byte entry in the table for each subfile, consisting of the relative block address of 
the record at the start of the subfile and, if the records are in blocked format, its 
displacement into the block. When you are creating a subfile, you issue a SETS macro to 
insert the address of the next available block or record as an entry in the subfile table. 
(Remember that you are creating subfiles sequentially, although you may retrieve the 
subfiles at random.) 


During retrieval, the SETS macro you issue moves the table entry for the subfile you have 
selected to the current relative address field of the DTFNI or DPCA file table; the file. may 
then be processed between the limits of the current relative address of the start of the 
subfile andthe logical end of the file or partition. This selective positioning of a file for 
subfile processing is a useful ability to keep in mind. 


For creation of subfiles (output), the SETS macro must be issued following the output of 
the last record to each subfile. SETS for output indicates termination of the subfile. 


For retrieval of subfiles (input), the SETS macro should be issued prior to the first GET of a 
subfile record. SETS for input initializes processing to the start of a eubHle. 
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15.7.6. ‘Initializing Position of a File or Partition (POINTS) — 
When you are processing within a file partition and want to get back to the start of it (that 
is, to reset the current relative block address from its present value to the partition- relative 
address of the first block of the same partition), “you will use the POINTS | macro that. is 
designed to b db just this. 
When you want to’ change partitions, you must first issue a SETP macro (15.7.4) to select 
the new partition, ‘and then issue the POINTS macro to. get to the beginning of that: 
POINTS initializes'the relative block address of the current partition. 
This is the format of the POINTS imperative macro: 
» AOPERATIONA» -<|. dash oi “OPERAND”) 27> 
. filename ro, “ ee . eeuiren 
. ‘a : ae uid, 1m ke Bon. 
Ste BP ook Pee : ear fl Rg eh . ‘ : ‘ (~ 
Positjonal Parameter Ue ee 
“filename et 
Is ‘the label of the corresponding DTFNI macroinstruction i in your program. 
(1) or 1 
Indicates that register cl, has been peroncee S with the address.of the DTFNI file. 
table." bod Beas, 
LABEL © ~AOPERATIONA “2 ; OPERAND.° ~ a eee bet A‘ 
HL, | Pecnrg PART.O! 
Apert pif 1). PIART.O 
oti | Pernt an 


Wane 
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15.7.7. Forcing End-of-Volume Procedures (FEOV) 


When you are processing a DTFSD file for input or output, and want to discontinue short 
of. the actual end of: this volume and to Peal eee the: next, you issue the’ FEOV 
unperauie: macro. * ‘ eats 


This macro initiates ond: of- veinne (EOV) srdeSauiaes on the current. volume, which -is 
closed just as if the actual EOV had been reached. Volume swapping is performed, and 
your next GET or PUT macroinstruction continues processing on the next sequential 
volume. The FEOV macro may be used only for DTFSD files; these: have only one volume 
mounted at a time. It may not be used for sequentially processed files described by the 
declarative macro because all volumes are always online, and. there is no “current 
volume” in the sense. used here. Bo Sie ; 


When you are processing sequential blocked input files and need to skip over the records 
remaining in a block in order to resume with the next block of the same volume, a 
different macro, RELSE, is available (15.7.13). 


This is the format of the FEOV macro: 







AOPERATIONA OPERAND 





| (filename) 
‘0 
ne | 





Positional Parameter 1: 


filename . 
'~Is the label of the corresponding DTFSD macroinstruction in the program. 


(1) or 1 
Indicates that you have preloaded-register 1 with the address of the DTFSD file 
table. 
Example: 
LABEL AOPERATIONA OPERAND A 


teow. | rere 


Treats the file described by the DTFSD macroinstruction, whose label is INFILE, as if 
logical end-of-volume address had been accessed. 
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15.7.8. Setting File Processing Mode (SETF) 


The SETF macroinstruction enables you to set the processing direction (change the type of 
file) for DTFSD files, or, sequentially processed DTFNI files, described by the. keyword 
parameter TYPEFLE=INOUT. You should not issue the SETF macro during your file 
processing; it should, instead, be issued between your terminating file processing (with the 
CLOSE macro) and your opening it again: or before the OPEN issued to the file at the start 
of yout program. 


This is ae format of the SETF macro: . 







A OPERATIONA _ OPERAND 


filename ) , (INPUT - 
$1) joureur 
1 UPDATE 









Positional Parameter 1: 


filename —.- 
Is the label a the DTFSD or DTFNI macroinstruction that defines the INOUT file. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the DTFSD or 
DTFNI file table describing the INOUT file. 


Positional Parameter 2: 


INPUT 
Indicates that the INOUT file is to be set for input processing, without sodatinG. 


OUTPUT 
Indicates that the INOUT file is to be set for output processing. 


UPDATE — 
Indicates that the INOUT file is to be set for input processing, with updating. 
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PUT 


15.7.9. Output of Sequential Disk Files (PUT) 


You will use the PUT imperative macro to create, extend, or update disk files processed 
sequentially. These are either files defined by the DTFSD declarative macroinstruction 
(15.5.1) or those files and partitions defined by the DTFNI and DPCA declarative macros 
(15.5.3 and 15.5.4). 


Essentially, the PUT macro handles record-level output for sequential files in either of two 
ways. It delivers an output record to data management in the current output area, if you 
are processing in IOAREA1 or IOAREA2. But, if you are building your output records in a 
work area (specifying WORKA=YES), the PUT macro delivers these to data management 
for writing to disk directly from there. Either way, the record is no longer available to you, 
once delivered. 


If your output records are unblocked, they are delivered singly to disk; if your records are 

to be blocked, data management handles blocking automatically for you from the work 

area. You must take care of blocking for variable-length blocks constructed in an I/O area, 

however, and you may optionally write out short blocks of fixed-length records. Both of 

these actions are easily accomplished: see 15.7.9.4 and the TRUNC imperative macro 
a (15.7.10). 


When your output records are blocked, or when you have specified a standby VO area 
(IOAREA2) but no work area, you must supply an index register via the IOREG keyword 
parameter of your DTF or DPCA macro so that data management has a place to put the 
starting address of the current record position in the output area (15.6.11). You. do not do 
this when building records in a work area, because you specify its address every time you 
issue the PUT macro. And, if you are processing unblocked records in a single I/O area 
(IOAREA1), you may reference these directly by means of the name you have assigned to 
the area and do not need an index register. 


An important point to remember is that, after data management writes the current output 
data to disk from the output or work area, it does not clear these areas. You must be 
careful either to clear the area yourself, or always to supply records — padded with blanks 
if necessary — which completely fill out the work area or I/O area. Otherwise, spurious 
characters left over from previous records may appear in your output data. When you are 
processing in a work area, it is freed for subsequent processing (but not cleared) each time 
data management moves an output record from there. into the I/O area for you. 


Sequentially processed DTFNI files with keys may also bie easily ones with the PUT 
macro; see 15.7.9.5. mast A 
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‘This is the format of the PUT macro: 





OPERAND 


( filename: ( workarea ) 
cl a 


A OPERATIONA 












Positional Parameter 1: 


filename ‘ 
Is the label of the corresponding DTFSD « or DTFNI macroinstruction that defines 


a _the output file. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTF file 
_ table. , | 


Positional Parameter 2: 


workarea 
. Is the label of the work area from which the output ‘record may be obtained. 


(O) or 0 
| "Indicates: that register 0 has been preloaded with the address of the work area. 


Af omitted, indicates that you have chosen, to reference the current record either by 

means or a register (IOREG: keyword parameter) or by. directly accessing the data 
relative to the name you have assigned to [OAREA1. You may use the latter method 
: only for unblocked records [processed in a ‘single 1/0 area. , 


NOTE: 


When the work area js used, the keyword paremneter, woRKA= YES must be present: 


in the DTF statement. 


15.7.9.1.— Creating a Sequential Disk File a =: ’ 7 


The PUT macro gives you the ability to create a new disk file and then to process it. 
sequentially: this amounts to using the disk file as a work file. You use the same DTF file. 


table to ‘describe the file when you create’ it and when you process it; ‘such. a file’ may be 
defined by a DTFSD or DTFNI declarative macro (15.5.1 or 15.5.3). The procedure is as 
follows: 


1. Define the file, specifying the DTF keyword parameter TYPEFLE=INOUT among the 
other parameters you need. 
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2. Open the file for output, using the. OPEN macroinstruction (15.7.1); then create the 
| file, using the PUT ‘macro to write your records to disk, 


3. Close the file, eeibg the CEOe macroinstruction (15.7.2). 


4. Issuing the ‘SETF_ macroinstruction (15.7.8), reset the file processing direction to 
~ INPUT or UPDATE. 


5. Reopen the file. 


6. Retrieve your records sequentially, via the GET macroinstruction (15.7.12), or 
optionally, update them with pairs of GET and PUT macros (15.7.9). It is important to 
‘remember that when you update with the PUT macro, you may never change the 
record length. 


7. Close the file. 

The following coding example shows how you might do this for a file ‘with the logical 
name INVNTRY. Once created as a TYPEFLE=INOUT file, the file is closed; after you reset 
the file processing direction to UPDATE, you reopen and update it by issuing paired GET 


and PUT macros to retrieve records and write them to disk. _ 


Example: 


LABEL AOPERATIONA OPERAND A 
16 | ae 


LIINvNTiy, | presDl | : SS eis ite EP | eT a, 


PE FILE ALNOUT., 





c 
J | 
7 < I< 
z 
~ 
re ie 
aL L 





. 
Se 
H 
[a 
< 
a 
U 


WANA K (UPDATE ee a aed eeteaeen. 
ORE Lb NVINTIRN, op bo be be a 


a ° 
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LABEL AOPERATIONA OPERAND > | i 


_ 
fone] 


GET, INVN TRY 


INAVNTIE 
INV, K 


—_ 


Other DTF keyword parameters, including required keywords not pertinent to the 
example, are not shown. . 


2. Must be INOUT file 
3. Other parameters are not shown. |. 
4. Creating file, using disk as work file 
5. Now reset file processing direction to update and reopen file 
6. Issuing paired GET/PUT macros to retrieve records, update them, and rewrite to 
disk. . . , cm 
7. Terminate file; cannot be Beeeseed until peope nea! | ~ 


15.7.9.2. Updating and Extending an Existing Disk File Processed Sequentially. 


The /ogical end of a disk file — the relative block number of the last data block — plus 1 is 
recorded by data management in the DTF and in the format 2 label of the file as its end- 
of-data (EOD) address. (See D.3.2.) In a DTFSD file, this address is also called the logical 
end-of-file (EOF) address. No EOF sentinel or other flag is recorded in the data area of the 
file to mark this point, and there is no data record in the block at the EOD address. 


When you are sequentially processing a nonindexed disk file in an update mode (that is, 
you have specified UPDATE=YES in the DTFSD or DTFNI declarative macro), you may 
extend the file beyond its current EOF record by the following procedure, which you will 
include in your end-of-file routine. (When you issue a GET macro and an end-of-file 
condition is detected, control returns to you at the address specified by your EOFADDR 
parameter in the DTF. You may not extend a file beyond its current volume by this means, 
but see 15.7.9.3.) 


1. Issuing a GET macro, you place the record to be added to the file in the |/O area 
(IOAREA 1 or 2) or in the work area you have specified. 


2. Issue a PUT macro, which causes the new record to be added. 
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3. Issue another GET macro and follow:it by a PUT macro; this will output the next 
record to be added to the file. 


4. TeEnale fhiek file Bg: issuing a CLOSE macro’ “when you have coe eee all yeu 
additions to it AHS: 7.2). 


An important point to MeinOHb is that you must have anticipated the eventual need to 
extend this file and provided for extension by the appropriate job control statements issued 
at the time you originally created it. Extension is: done automatically for you by data 
management through the disk space management routines of the OS/3 Supervisor: you 
never need to call the Supervisor EXTEND» macro in your’ program: 


Another point to remember is that you must not. .issue two PUT macros in succession in 
the update: mode; this will be flagged as an invalid macro Be qUaNCe (byte 0, bit 6 ot 
filenameC haus B)). ; 


15.7. 9.3. ‘Extending an. Existing DTFSD Gumue File 


Extanding a Sequential file within your EOFADDR routine is aiscuaeea in ‘415. 7.9.2.. You 
have another means available for extending an existing sequential file: processing it in the 
output. mode (that is, by specifying TYPEFLE=OUTPUT in, the DTFSD declarative macro, or 
resetting the direction of file processing to OUTPUT with the SETF imperative macro 
(15.7.8)). This procedure also requires that you issue > appropriate job control. statements, 
which are discussed in what follows. . a pon 


First, the current last volume of the file is mounted; for a disk file described by the DTFSD 
declarative macro, this is always a specific volume because only one volume is mounted at 
a time. (All volumes of a DTFNI file, processed sequentially or not, are always online.) 


When you issue an OPEN macro for the file, if you have specified the appropriate job 
control statements, data manegemeyt will pasition: the file to its current logical end- et -file 
(EOF) address. 


You then issue the PUT macros HeC eee any. to add records beyond 1 the current logical EOF. 


If you need hen allocate additional disk velanés to the file, and? you ‘may continue to 
extend it beyond its current last volume to subsequent volumes. 


The OS/3 job control statements you need to specify to extend a sequential disk file by 
this method are discussed in detail in the job control user guide, UP-8065 (current 
version). Briefly, what you need in your device assignment set is an LFD statement that 
contains the logical name of your file (the name by which your program references it) and 
indicates by an EXTEND (third positional parameter) that the extend mode of processing is 
to take place: the sequential file will be extended by appending the new records to the 
present end of the file. 


It is important for you to remember that all LFD names within a job step must be unique; if 
more than one file is given in the same name, only the last one to be specified is available 
for any operation — including extension by this method. 
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15.7.9.4.. Output of Blocked Records, Sequential Disk Files 


As you are forming variable-length records for output to a besaucmaly ss beeceal disk file 
via the PUT. macro, you will be:determining the length. of each record and placing this 
information in the first two bytes of the 4-byte record descriptor word (RDW), at the head 
of each record (14.3.2). This information is contained won the record and is always in 
the 1/O area whenever the record is. 

When you are eutpuHIAG ‘ vadable: conan blocked pecans ior an 11/0 area to disk and are 
not using a workarea, you must.test whether the next record will fit:into the remaining 
space in the I/O area before-you issue the PUT macroinstruction for it. Data management 
informs you of the amount of space remaining in the I/O area after each variable-length 
record is moved in by a PUT macro; it*does so'by placing the number of bytes of residual 
space into the general register you have: specified (via the VARBLD: keyword parameter of 
the DTFSD or DTFNI macro or the DPCA macro (11.6.34). If you find that the next record 
will fit, add it to the current block with the PUT macro. If you find that it will not, you 
instead issue a TRUNC macro to write out the current block to disk and free the entire 1/0 
area for building the next (15.7.10). Data’ management will ‘calculate the block size and 
will enter it into the first two bytes of the 4- byte block peeeerDtOr word Neel as vanes 
in 14. 3:2, before writing the block to disc. ~ 


On the other: hand, Wier you are forming ¥ your : Warlable- janet blocked records in a work 
area, each PUT macro you issue causes data management to test whether the record it 
moves will fit into the |/O area. If it will, it is added to the block currently being built; if it 


will not fit, data management first writes out the current-block and then starts a new block 


with the current record. 


15.7.9.5. Output of Sequential DTFNI Files With Keys 


Files defined by the DTFNI-declarative macro and processed sequentially may have a key 
associated with each b/ock of data. Before you issue a'PUT macro to output such a block 


to disk, you must place this key at the head of the block (just as you would before issuing: 


a WRITE macro with an ID positional parameter for direct access method output of blocks 
with keys): When you issue the PUT macro, data management will write the key and data 
portion of the block to disc. Subsequent sequential retrieval of blocks having keys (via the 
GET macro) will, similarly, cause transfer°of both: the key and data. Remember that-data 


management will perform the normal. blocking and deblocking for DTFNI files processed 


sequentially. 


Another point to remember is that, when you are creating or updating nonindexed files 


with keys, using the PUT macro, you must specify the key length via the KEYLEN keyword 


parameter of the: DTEN| or DPCA msero meteucton see 6. 13). 


FOr, 


ee, 


UP-8068 Rev. 4. | SPERRY UNIVAC OS/3° .. 15-81 


BASIC DATA MANAGEMENT » 





15.7.9.6. Optional Sequential Output Files 


When you have a program that you anticipate will not invariably be called on to process a 
particular sequential output disk file each time it is executed, you should designate this file 
as optional by specifying OPTION=YES in the DTFSD or DTFNI macro (15.6.16). On the 
occasions when you do not require ‘the file to be output from your program, you need 
merely omit the device assignment set of job control statements that usually allocate the 
file to a disk. When your program executes the OPEN macro for the. optional file, the OPEN 
transient marks the file as optional, and it disables the PUT macro, mechanism SO that no 
I/O is performed. — 


You should not ‘fg to specify the OPTION keyword parameter for an optional file: if you 
do forget, and the file has not been allocated by job control when your program is 
executed, it is impossible to process the file. Data management will transfer control to the 
address of your error routine. 
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15.7.10. Output of Short Variable Blocks to Sequential Disk Files (TRUNC) 


The. TRUNC imperative macro is used with sequentially processed, variable-length, output 
files, defined by the DTFSD or DTFNI macros, to enable you to write short blocks of output 
data to disk. Its use is mandatory with variable-length, blocked records that you build in 
the output I/O area. Its function is to notify data management that the block currently 
being built is to terminate and is to be written. out to disk. Data management calculates 
the block size and inserts it in the first two bytes of the block descriptor word (BDW) 
before it writes the block to disk. a : : 


When you have formed a variable-length record to be added to the block building in the 
I/O area, you must determine whether there is room for it in the remaining space in the 
I/O area before you issue the PUT macro. You compare the current record length, which 
you have placed in the first two bytes of its record descriptor word (RDW), with the 
number of bytes remaining in the |/O area. (Data management informs you of the space 
left in the I/O area by placing the number of bytes of residual space in the general 
register that you designated by specifying the VARBLD keyword parameter in the DTFSD, 
DTFNI, or DPCA macro (15.6.34); it updates this number each time a variable-length 
record is added to the current block by a PUT macro.) 


If the current record will fit in the space remaining, you will issue a PUT macro to add it to 
the current block. But if it will not, you issue a TRUNC macro to write the current block to 
disk and to free the I/O area for building the next block. A subsequent PUT macro will 
then start off the next block with the current record; the TRUNC macro resets the IOREG 
index register to point to the new current area address of the next available output I/O 
area. 


This is the format of the TRUNC macro: 





A OPERATIONA OPERAND 








filename 
inne 
1 


Positional Parameter 1: 


filename 
Is the label of the corresponding DTFSD or DTFNI macroinstruction in the 
program. 


(1) or 1 
Indicates that register 1 has been preloaded with the address of the DTF file 
table. 


Ors, 
, . 
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Example: 


LABEL AOPERATIONA OPERAND A 
1 10 16 
ee ti, | mene bare 


Sends to the output device -the short block of records. accumulated by PUT — 
macroinstructions since the last TRUNC :was issued or since a full block. of records was © 
sent automatically to the output device for the file described in the DTF macroinstruction © 
whose label is OUTPUT. 
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WRITE 


15.7.11. Random Output of Records to Disk (WRITE) — 


The WRITE imperative macro is a block-level output processing macro that, in its various 
forms and uses, provides you with the following capabilities with randomly processed disk 
files defined as output files by:the ioe or. DIFNI coclarave.n macros, or as a eal 
files by the DTFNI. macro: a ee a 


= creating a newly allocated file; 

™ updating a previously created file by rewriting blocks to their original locations; 
= extending a file by generating data blocks in space newly allocated to it; 

= overwriting unwanted data in an expired or newly allocated file; 

™ recording the logical end of a file or partition; and 


# moving the disk access arm to a new track and ensuring that the new track is 
initialized. 


Three forms of the WRITE macro output a block from main storage to disk; the main ( 
storage address from which your data is written is contained in the location specified by 

the IOAREA1 keyword parameter of your DTF. Its input counterpart for disk files that may 

be processed randomly is the READ imperative macro, which is also a _ block-level 
processing macro (15.7.14). 


! 
Because these two operate a block-level, you must control any record blocking and 
deblocking that may be necessary, as OS/3 data management handles this function 
automatically for you only for sequentially processed DTFSD and DTFNI files. 


For disk files you define with the DTFDA macro, of course, this is no problem, as only 
unblocked record format (fixed- or variable-length) may be specified for these files. For 
randomly processed DTFNI files, however, in which you may have blocked records, you will 
need to control their blocking and deblocking with the PUT and GET macros, used in 
conjunction with READ and the WRITE,KEY or WRITE,ID form of the WRITE command 
(15.7.11.4 and 15.7.11.5). 


In all uses, you must issue a WAITF imperative macro (15.7.16) after each READ or WRITE 
macro you issue, to ensure that the intended data transfer has taken place, before issuing 
another imperative macro. Remember also that none of your transferred records will be 
check-read for parity unless you specify the VERIFY=YES keyword parameter in your DTF 
macro; check reading necessarily increases the execution time for each WRITE operation 
(15.6.33). 
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Another DTF keyword parameter involved is IDLOC, which enables you to have the relative 
disk address (ID) of your block returned to a specified field. The form of the returned ID is 
governed by your specification of another DTF keyword parameter, RELATIVE, which you 
might also review (15.6.22). The uses of the IDLOC keyword parameter are explained in 
15.6.7 and further discussed in what follows. . 
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15.7.11.1. Creating a Random Disk File by ‘Sequential Load (WRITE,AFTER) 


This is one form of the WRITE command you may use to create a file: 





A OPERATIONA OPERAND 





(1) 


wee 
1 





The second positional parameter, AFTER, specifies that the current block in main storage 
is to be written as the next sequential block on the current track and that the remainder of 
the track is to be cleared. If this current block, when written, occupies the last position on 
the track, data management sets the /ast block on track accessed bit (byte O, bit O) in 
filenameC after completion of the WAITF macro. (See Appendix B for the details on 
filenameC.) You should check this bit after each issue of the WAITF macro, and be 
prepared to move to another track if it is set, using, for example, the WRITE,RZERO form of 
the WRITE command (15.11.2) or the CNTRL imperative macro (15.7.15). 


You should review the AFTER keyword parameter of the DTIFDA and DTFNI declarative 
macros; this parameter must be specified when you use the WRITE,AFTER form of the 
WRITE command and precludes your use of the WRITE,ID function (15.7.11.4). Data 
management does not automatically preformat the file at OPEN when AFTER=YES is 
specified. 


In the first positional parameter, filename represents the label of the DTFDA or DTFNI 
declarative macro; (7) or 7 indicates that you have preloaded general register 1 with the 
address of the DTF file table. The first positional parameter is specified in the same way 
for all forms of the WRITE command and will not be discussed further. 


If you want to store the relative disk address or ID of the next block in the file or partition 
you are processing, you would specify the IDLOC keyword parameter in the DTF (15.6.7). 
The form in which this ID is returned to you is governed by your specification of another 
keyword parameter, RELATIVE, which you should review (15.6.22). 


You have two basic ways of using the WRITE,AFTER imperative macro to create a new 
direct access disk file: a simple sequential load process that proceeds from the file start 
through all the tracks in succession, and another use, in conjunction with the 
WRITE,RZERO macro (15.7.11.12), which enables you to select the tracks to be filled in 
whatever order you choose. Because the WRITE,AFTER macro (having written a block to a 
file on a variable-sector 8411, 8414, 8424, 8425, 8430, or 8433 disk) then overwrites the 
remainder of the current track with binary O’s, you may also use it (with or without the 
WRITE,RZERO macro) to expunge unwanted data from an existng variable-sector disk file. 
You cannot do this if the file resides on the fixed-sector 8416 disk in OS/3. 


Py, 
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When you open a newly allocated direct access file the first time for output, ‘the OPEN 
transient positions you automatically at the head of relative track 001. If you are going to 
use the WRITE,AFTER macro, you have specified the AFTER keyword, and no 
preformatting has been done (if the file is on a variable-sector disk). If you issue 
successive WRITE,AFTER imperatives, each followed by a WAITF macro (15.7.16), you 
effect a sequential loading of your file, in the simple order in which you ‘present your 
blocks to data management. You do not use the SEEKADR field’s contents to control this 
macro, for the WRITE,AFTER macro used this way automatically shifts from track to track 
and cylinder to cylinder sequentially. However, you must arrange to move the contents. of 
the IDLOC field (to which the following WAITF macro returns the ID of the next block in 
physical sequence in the file) into the SEEKADR field in order for this method to work. 
(One easy way. for bringing this about. is to define.the IDLOC and the SEEKADR fields as 
the same area in main storage, as described in 15.6.7.) The file-filling sequence continues 
until you reach logical end of volume and an error condition in filenameC indicates that 
you have exhausted your file space, unless you have terminated loading sooner (as, for 
example, when reaching logical end of file (EOF) in your input file). You do not, in this 
method, need to test for setting of the /ast block on track accessed flag in filenameC 
because of the automatic movement to the head of the next track that data menagement 
Perronms: aS . 4 . Rage 2 7 


You do heed to Leap your fingue on track fill, Rowever: when ‘you use the WRITE, AFTER 
macro in the second method mentioned, ‘tor this controls: your issue o the WRITE, Berne 
macro: to select the next track to be meee > 


You should: note a fev more noite about: this area The first is ‘hie last block on a irack 
accessed flag is set by OS/3 after you have issued the WRITE,AFTER macro that writes 
the block in the last position of the current track; in some other data management 
systems, this hae is not set until you issue a macro to write the next peck: whic) will not 
te on ie track... ; we 


Anather- point’ is: ahat: the sattitig of this ce must be tested fori in your program inline’ 
because accessing the last block is not a condition that causes control to transfer to your 
error routine: if you test fflenameC for this flag only in your error routine, you will miss it. 
A third point.is. that, although the WRITE,AFTER macro does not require a.seek address to 
guide it, the-WRITE,RZERO. macro does; you must, therefore, arrange to increment. your 
SEEKADR fields’s. contents to the new relative track address you want before you issue it. . 
You will probably have specified re/ative track addressing (RELATIVE=T) when you‘use this 
method. for creating a file with WRITE,RZERO and WRITE,AFTER, but you may also use 
relative record ae EE AUIVE Rh: eewen this is harder to control. 


One final’ seins is most: important if your file resides on an 8416 disk. Because. of the 
fixed-sector format of this. disk in OS/3, the action of the WRITE,AFTER macro is 
significantly different from the foregoing description in that the macro, having written a 
block, does not set all fields to binary O in the remainder of the blocks on the track. On the 
8416 disk, moreover, there is no record O at the head of the track from which data 
management can be informed of the amount of unused space. For these reasons, you 
must always fill each 8416 disk track completely when you use the WRITE,AFTER macro. 
If you write only the one block at the head of the track, for example, and then pass on to 
another track, the residual data in the 39 remaining blocks is still there and may produce 
unpredictable results when your program encounters it in later retrieval operations. 
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. 15. 7. AT 2. Selecting and | Initializing a New Track DWEITE, RZERO} 


The (orn: of the: WRITE command to .use for moving the disk! access arm to a new track, 
and: ensuring that the new track is ace is: i eg S624 





A OPERATION A OPERAND.. 






(1). 


‘ | of i 





Here, the second positional parameter, RZERO, specifies that. data management. will 
position the file for subsequent processing at the relative track address you have preloaded 
into: the field specified by the SEEKADR keyword. parameter of your DTF (15.6.24). This 

means that. you have. selected: a new track, or that the track specified is to be treated as a 

new track, and that writing will begin at the first .record on this track. Note that this form 

of the WRITE command does not actually output a record: it merely repositions the file so 
that you may write the subsequent records beginning with the first.record of-a new track. 

For writing’the next record, — -must follow this: form with. the SITE) AFTER roe of. pe 
ee command, ‘in a ele <r : Be ae be 


Because fhe WRITE, AFTER macro clears the rest of the- current track, “this: 
WRITE,RZERO/WRITE,AFTER combination is one you may use to create a new file or to 
overwrite erase’ Gale HOI an: apres or ney aimee file ¢ ona WaMEDIG: sector disk. 


If you want to store the faleuue disk: address: or dentition (ID), of the next blow: in-the file: 
or partition you. are’ processing with the WRITE,RZERO/WRITE,AFTER macros,.you would 
specify the IDLOC keyword parameter in the DTF (15.6.7).:The form in which'this ID is. 
returned to’ you is governed ‘by your Specification of another :keyword® parameter, 
RELATIVE, which you should also review (15.622). No ID is‘returned by the WAITF. macro 
that. follows: the: WRITE, BEERS macro; the contents: of the. late field” are pole hasan 


Use of the WRITE, RZERO macroinstruction requires that. you specify AFTER=YES in: your 
DTF; because data. management does not preformat the file on. a variable- sector disk wien 
this ney Olea is specified, you mays not issue ‘the i dea macro to. it. 


Peau 


"gen 
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WRITE,AFTER,EOF 


15.7.11.3. .Recording the Logical .End-of-File (WRITE,AFTER,EOF): = °° 


This, form of the: WRITE macro may-be used to record the logical end of data or end-of-file 
address in the DTF. Data management also records it in the disk format 2 label: 

















LB OEERAUIONS _OPERAND 





_( filename AFTER, EOF | 
(1) 
es 


The logical end-of-file (EOF) or end of partition is the relative disk address of the block. one 
beyond. the block (containing data) that is written the farthest: or deepest. into. the file .or 
partition. It is the address | one block. beyond the. highest » cused relative disk address, and 
there is no. data. that belongs. to your file. there. Data management uses this. address, 
which... ‘it also. knows as the end- of- data. ID (EODID), to prevent your reading extraneous 
data outside of the limits: of the current, partition or file space on:disk, and it. recasds. Me: 
EODID.. jn the disk format 2 label. (See D. 3: ih ees . Bo a 


If you issue a READ, ID macro that Geictcncc. a Block whose relative disk sdeiees, ekcasee 
the EODID,.data. management sets. the /nvalid /D flag (byte O, bit: 1) in. filename€, issues. 
error message DM24, and branches to your. error routine. (See Appendix. B.) You: may, on, 
the other hand, write. at. or beyond the current. logical end. of nile " yeu have provided for: 
file. extension. ae cS wae es ge rad : 

You should not need to issue the WRITE,AFTER,EOF macro..in a new program: written in 
OS/3, because data management automatically keeps track of the progress your program. 
is making | as it fills the file, and automatically records the EODID on file close. However, if. 
you have. a. program coded for some. other. system, where it was necessary for your ‘to issue | 
the macro, you need | ‘not remove. your WRITE, AAFTER,EOF macro call. from -it. . asta 


The. WRITE, AFTER, EOF macro does not ‘output. a. ‘block, nor does it rake an 1D return to 
the IDLOC field. It is however, necessary for you. to place: in the SEEKADR field the relative 
disk address of the block that data management is.to use in calculating and recording the 
EODID. Usually, this is the address of the block just written. 


Note, ‘however, ‘that che. peniian name is never eed in the first jocitonal Racdmietse. i 
you ‘need to know where the end of a subfile occurs. within a partition,.you must maintain. 
your own end-of-subfile data. record; data management does not provide. this service;:to - 
you. On the contrary, it is possible to process through the end of a subfile to the poeta 
EOF or end of partition. % | al “ 


Remember. to specify her keyword parameter AFTER in the DTF. when-\ you end to issue. 
the WRITE, AFTER, EOF form of the WRITE macro (15; 6.2); otherwise it-will be flagged as: 
an invalid macro (byte O, bit 6 of filenameC). 
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WRITE, ID. 


15.7.11.4. Creating or Updating Blocks by Relative Disk Address (WRITE,ID) © 


You may use the following form of the WRITE imperative: macro for Creating a direct 
access file or for updating an existing one on disk: eas 










A OPERATION A _ OPERAND 












[name] WRITE 





filename , ID 
(1) - 
1 


The second positional parameter, /D, specifies that a search is to be’ made in the output 
file for a block whose relative disk address (ID) matches the content of the SEEKADR field 
in your program (15.6.13): The ID you present to data management in this field may not be 
negative or zero; it must be in the form you specify with the RELATIVE keyword parameter 
(15.6.22). If you issue the WRITE,ID macro to process a file, you must specify the WRITEID 
keyword parameter in the DTFDA or DTFNI declarative macro’ defining the file (15. 6. 35); 
the AFTER keyword must not be specified (15.6.2). If the blocks in your file are keyed, you 
must revel) the jengt of these keys with the ses oe parameter (15. 6. ere 


Beforé you issue the WRITE,ID macro, you'must ensure that. ‘the correct relative ‘disk 
address is contained, asa fixed-point binary number in the form you have specified with 
the RELATIVE keyword, in the 4-byte SEEKADR field in your program. If you” define the. 
IDLOC and the SEEKADR fields to be the same physical area in main storage, data 
management is, in effect, providing a new relative disk address to your WRITE, ID macro 
ae ee (Refer to 15. 6. ie . 


In addition’ to providing your WRITE, ID macro with the correct ID, you must have the new 
block already formed in the 1/O area before you issue the macro. If. your file contains keys, 
moreover, you must place the key of each block in the I/O area‘ahead of the record proper 
(or ahead of a string of blocked records), allowing for the block descriptor and record 
descriptor words (BDW and RDW) as appropriate. In executing the WRITE,ID macro, data 
management locates the relative disk address you have specified (if ‘it can) and writes the 
entire block at the location, nemelng: its key if yours is a keyed file. : 


Following your issue of the WRITE,ID macro — or of any form of the WRITE macro — you” 
must issue a WAITF macro before issuing any other to the file. This is necessary to ensure 
that: the intended 1/O is completed. Among other things,’ the WAITF macro returns the 
relative disk address of the next block in physical sequence in the file to your IDLOC field, 
if you: have specified this keyword, in the form you have specified with the RELATIVE. 
keyword. If the relative disk address specified is not located, data management set the 
record not found flag (byte 1, bit 3) in filenameC, which you should test in your error, 
routine when you are lipdating a file. If the block written by the WRITE,ID macro occupies _ 
the last possible position on the current track, data management sets the last block on. 


ae, 
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track accessed flag (byte O, bit O) in filenameC, but, because this is not an error condition, 
control does not pass to your error routine. If you are controlling movement through your 
file by incrementing the relative track number when you reach the end of track, you must 

test for the setting of this flag inline. 3 


There are two ways to use the WRITE,ID macro to create a new direct access file: a simple 
file-filling operation that uses this macro alone, and an operation writing on specific tracks 
that you select and move to, via the CNTRL macro, followed by the WRITE,ID macro. - 


When you open a new DTFDA or DTFNI file for the first time for output on a variable- 
sector disk,*. unless you have specified: AFTER=YES in the DTF. (15.6.2), the OPEN 
transients preformat every track in the file, writing the count fields throughout at intervals 
corresponding to your specified block size, and then position you at the head of relative 
track O01, ready to write the first block. By providing your WRITE,ID macro with the 
relative disk address for the first block, and thereafter incrementing the contents of your 
SEEKADR field, you may fill your file at will, in any sequence of re/ative track or relative 
record addresses. If you simply increment the relative record number in the SEEKADR 
field, for example (having specified RELATIVE=R), before each WRITE,ID macro issued, you 
achieve a file load in the simple sequential order in which you present your blocks. In this 
circumstance, you have no need to test for the /ast block on track accessed flag because 
data management automatically shifts you to the head of the next relative track. When you 
close the file, data management records the end-of-data ID in the DTF file table and in the 
disk format 2 label; you do not need to issue the WRITE,AFTER,EOF imperative macro for 
this.| On the other hand, if you need to structure the data in your direct access file in 
such a way that you must skip relative track O01 or certain other tracks during its initial 
loading, the first imperative macro to issue after opening the file might be the CNTRL 
macro (15.7.15), guided by a relative track address you have placed in the SEEKADR field 
to position you to the head of the first track you wanted to receive your data. After 
execution of the CNTRL macro, simply issue successive WRITE,ID macros, incrementing 
the record number in the SEEKADR field until end of track; then increment the relative 
track number before issuing the next CNTRL macro. (You cannot pair the WRITE,ID macro 
with the WRITE,RZERO macro for this mode of processing, because this macro also 
requires you to specify AEIEN ies in your DIF, and this is incompatible with using the 
WRITE,ID macro.) 


Updating an existing direct access file with the WRITE,ID macro is conceptually different 
from creating a new one, although the action of the macro is the same. One thing to keep 
in mind, however, is that the new block is written in the place of the old one on disk, and 
data management requires that it be the same length. New blocks written to an existing 
file must have the same length as existing blocks. The BLKSIZE specification is checked at 
file open time against the block size recorded in the disk format 1 label; if these are 
unequal, data management issues error message DM17 (INVALID BLOCK SIZE SPECIFIED) 
and branches to your error routine. (Refer to Appendix B.) 


*The variable-sector disks used with OS/3 data management are the SPERRY UNIVAC 8411, 8414, 8424, 8425, 8430, 
and 8433 Disk Subsystems. The SPERRY UNIVAC 8415, 8416, and 8418 Disk Subsystems are fixed-sector disks and 
are already preformatted at OPEN time. 


tin fact, because this macro requires that you specify the AFTER keyword in your DTF, and you cannot issue the WRITE,/D macro if you 
do, you cannot use WRITE,AFTER,EOF. 
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If you know the relative disk addresses of all the blocks that” require updating, and you 
have the update information formatted to replace the entire block (including its key, if this | 
‘is a keyed file), then’you neéd not read your ‘existing blocks into main storage. You need 
merely issue successive WRITE,ID macros to update the file, providing the relative disk 
agdngsses in the order of the update RoTOpmauon in your peut file. 


-On ‘the other hand, if you must read the old blocks to detarifiine’ whether or where to’ 
update them, you either would issue the READ, ID macro, process each incoming block, 
and then issue the WRITE,ID macro to update each block that requires it, or you would 
issue the READ,KEY macro followed by the WRITE,KEY macro. Remember the difference 
between the IDs returned after execution of the two different READ macros, and plan your 
use of the IDLOC field contents accordingly (Table 15—5). To Lileks the’ DEOe and 
SEEKADR fields in ee mode is. not good piBeless: ; 


Another point to Kap in iiiind about peeing a keyed file is that you must not only’ specify’. 
the length of keys with the KEYLEN keyword parameter in your DTF, but you must also - 
provide a key for each updated block in your |/O area. Both the key’ and the data fields’ ce 
the ee on ai ‘are updated when Jyou E speatly this: Reywotde . - 


Data management does not radia: you a-direct means a changing sal the key . a block — 
on:disk. You may do so with'the: WRITE,ID: macro only by presenting data ‘management 
with a block in main storage that contains°a new key field and a data portion that is’ 
identical to that:already on disk. Of course, this can be done by reading in the whole block - 
in: question and updating only the key field before copying it all back to disk with the 

WRITE,ID macro. (You must: not attempt this with the READ,KEY/WRITE,KEY macros, - 
because with this pee you snould not “hanes the key of a block Betore returning it to the ae 
disk file.) ¢ go pan ey 


A ‘massive mapdate of a direct: access” file With: the WRITE, ID macro may be made more — 
efficient if the update information.is presented:in the physical order of the blocks that it is - 
intended for’on disk; this is especially true if the file has been created ‘by using record ‘ 
interlace -and a LACE factor tailored to the updating program (15.6.8). Having a keyed file ~ 
-precludes. this. possibility, because you. cannot create a keyed file without: specifying the — 
KEYLEN parameter, and you cannot use record interlace if you do. In deciding whether to 
lace a direct access file that does not contain keys, you need, of course, to consider the 
additional costs of sorting your input-file before using it in your update program. . 
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15.7.11.5.. Rewriting Randomly Retrieved Blocks to Disk (WRITE,KEY), ~ 


When you want to effect a direct-access rewrite, or updating, of a block that you have just 
retrieved.with the. READ, KEY. form of the READ command Pn 7.14. 2), you will use this - 
form of the WRITE macro: 





A OPERATION A 






OPERAND ~— 


_( filename ) , KEY 
«0 





_ [name] - 


Here, the second positional parameter, KEY, specifies that the block just read, by a: 
READ,KEY macro is to be rewritten to its original location on disk. Both the key and the | 
data field will be. updated. Remember to specify WRITEKEY=YES in. your DTF (15.6:35).. 
You should also remember that if the new block is longer than the old, the new block will | 
be truncated; if the new block is shorter, data. management will pad out the original field 
with binary zeros. In either. case, the wrong ‘length error flag (byte 1, bit 5) will be set in. — 
filenameC (Appendix B). You should check this bit after. Seung the WAITF macro that 

must follow each WRITE,KEY macro. oo . wos 


Another point to remember is that, because each block to be rewritten by the WRITE,KEY 
form must first be retrieved by the READ,KEY macro, consecutive issues of the WRITE,KEY 
form constitute a sequence error and will be flagged as an invalid macro Sequence (byte 0, 
bit 6, of filenameC). et 4 


Because the WRITE,KEY macro. does not conduct a search but relies on the search made 
by the preceding READ,KEY macro, it is not possible to add new records to a file with the 
WRITE,KEY macro alone. It is guided neither by the contents of the SEEKADR field nor by 
the contents of the KEYARG field. The only way the WRITE,KEY macro could be used to 
create a new file would be to originally create one whose keyed records contain blank or 
zero-filled data portions and then use the READ,KEY/WRITE,KEY combination to overwrite. 
each null. data portion with actual data. But this would be an inefficient and: unnecessary 
way to go about creating a file. ny. esses 


If you want to store the ID of the block updated by the WRITE,KEY macro, you ‘should 
specify the IDLOC keyword parameter in your DTF (15.6.7). The form in which this relative 
disk address is returned to you is governed by your specification of another DTF keyword 
parameter, RELATIVE, which is described in 15.6.22. 
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GET - 


15.7.12. Retrieving Records From Sequentially Processed Disk Files (GET) 


You use the record-level GET imperative macro to obtain records of all types, one at a 
time, from DTFSD files or from sequentially processed DTFNI files, opened for input 
processing. Data management reads the records, automatically deblocks them if they are 
blocked, and delivers each unblocked or deblocked record to you. If you are processing in 
an |/O area, it places the records there, one at a time; if you are processing in a work 
area, it delivers the records there from the I/O area. 


When you use a work area, you must remember to specify WORKA=YES. in the DTF 
declarative macro (15.6.35). Because you specify the address or label of the work area to 
be used each time you issue the GET macro, you may use more than one work area, and a 
different one each time. 


When your input records are blocked, and you have no work area, or if you provide two 


1/O- areas, you must also provide an index register (using the IOREG keyword parameter of 
your: DTF (15.6.11)), into which data management places the Starting address (in the 1/0 © 
area) of the next available record. An index register should not be used to keep track of the © 
current work area, because you specify this with each GET macro; if you elect to use two 


or more work areas, it is important to use them consistently. 


This is the format of the GET macro: 









A.OPERATIONA - 





OPERAND 


filename | wo acaees 





positional Parameter 1: 
filename 
macroinstruction. 
(1) or 1 


‘Indicates that you have breibaded: register 1 with the address of the DTF file 
table. 


Specifies the. label of the DTFSD or sequentially processed DTFNI declarative 


Se, 
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Positional Parameter 2: 


workarea 
Is the label of an area into which data management moves the current record for 
you to process. (A different work area may be used for each GET macro.) 


(O) or O — 7 
_ “Indicates that you have preloaded register O with the address of a work area. 


om Posilonal Parameter 2 when you do not use a work area. 


If you apse aaly one |/O area in your DTF, and your input records are not blocked, you 
may access the data directly in the |/O area (IOAREA1). Otherwise, you must specify an 
index register with the IOREG keyword parameter or use a work area. Table 15—9 shows 
the uses of an index register and work areas, and the actions taken by data management 
under the various combinations possible. 


Table 15—9. Use of IOREG Keyword Parameter for Processing Blocked or Unblocked Input Disk Files Sequentially with GET 
Macro 


Number of Number of Record : : 
aes Are Work Areas F t ROBES 

= bi sade Specification Data Management Action 
Blocked | Unblocked | Hoquited 


Be ss DMS delivers each unblocked record directly to user in IDAREAT: 


DMS’ deblocks in iIOAREA1 ‘and delivers each deblocked ecded to workarea specified 
in positional parameter 2 of GET macro. 


DMS delivers unblocked record from |OAREA1 to workarea specified in GET macro. 


DMS deblocks in one IOAREA and delivers deblocked records to other |OAREA for user 
to process, 


available for overlap processing. 


DMS deblocks in one |OAREA and delivers deblocked records to workarea specified by 
_ GET macro. Other areas are available for overlap processing. 


DMS delivers unblocked record to workarea specified by GET macro, from tOAREA specified 
by 1OREG. Alternates are available for overlap processing. — 





oS = DMS gelivers unblocked record to IOAREA specified by [OR EG. Alternate areas are 


When you are retrieving blocked input records with the GET macro, you may come to a 
point in the current block where you want to skip over the remaining records to process 
the first record of the succeeding block; the RELSE imperative macro is designed for this; 
see 15.7.13. 


You have a different imperative macro, FEOV, available if you want to discontinue 
processing the current vo/ume of an input DTFSD file in order to begin processing the 
next. This macro may not be used with sequentially processed DTFNI files, however; see 
15.7.7. 
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15.7.13. Skipping Records in Sequentially Processed Input Blocks (RELSE) 


When you are processing blocked input records with the GET imperative macro ‘from 


DTFSD files or sequentially processed DTFNI files, you may reach a point at which you 


want to skip over the remaining records in the current block and to commence processing 
with the first record of the succeeding block. To effect the skip, you issue the RELSE 
imperative macro; the next GET macro. you, issue mene the first record .of the next. block 
available to you (15.7.12). | 


The format of the RELSE wit is simply: 


filename 
(1) 
ee 








OPERAND 












A OPERATION A 





Positional Para meter: |e 


filename 


Is the label in your program of the DTFSD or DTFNI declarative macro defining | 


the file you are processing sequentially. _ 


(1) or 1 


Indicates that you have preloaaea aehisral register 1 with the “agdress of the | 


PIES? or DTFNI file table:. 


When you want ‘to terminate processing the current volume of a sequentially processed 
input file defined by the DTFSD declarative macro in order to begin with the next volume, 
you will use the FEOV imperative macro (15.7.7). | 


. 
: Os, 
% 
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ae 


15.7.14. Random Retrieval from Direct Access Files (READ) _ 


The READ imperative macro is a block-level input processing macro that, in its two forms 
and various uses, provides you with the following capabilities for randomly processing disk 
files defined as input files by the DTFDA and DTFNI declarative macros, or as input/output 
files by the DTFNI macro: 


= retrieving a block or record by means of its relative disk address (ID), which you 
specify; 


# retrieving a block by searching for its key, to be matched with a key you specify (the 
search begins at an address that you also specify); and 


= updating a previously created file. 


The READ macro causes a block to be retrieved from disk and to be read into. main storage 
at an address specified by the IOAREA1 keyword parameter of your DIFDA or DTFNI 
declarative macro, when you specify only a single |/O area (15.6.10). On the other hand, 
when you are processing DTFNI files.and have specified a second |/O area (IOAREA2; see 
15.6.11), the main storage address is contained in the index register you must specify with 
the IOREG keyword parameter (15.6.11). (The DTFDA declarative macro, as you know, 
does not support either the IOAREA2 or the IOREG keyword parameter.) 


Because the READ macro operates at block level, and OS/3 data management handles 
blocking and deblocking automatically only for sequentially processed files, you must 
control any deblocking necessary when you read blocked input files defined by the DTFNI 
macro. This deblocking you will take care of via the GET imperative macro (15.7.12), after 
the READ macro has placed a block into main storage from disk. AS you know, you may 
not specify either of the blocked record formats for a DTFDA file. If your ‘““unblocked” block 
in a DTFDA file actually.contains more than one logical record, therefore, you must tend to 
the deblocking yourself. The GET macro is not supported for DTFDA files, however, and is 
flagged as invalid if issued to such a file. The best solution to this quandary is probably to 
avoid it by defining such a file with the DTFNI declarative macro in the first place. 


Another important point to remember is that, after each READ macro you issue, you must 
issue a WAITF imperative macro before you issue any other imperative (15.7.16). This is 
necessary, to ensure that the intended transfer of the block from disk to main storage has 
indeed taken place. 
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_If you want data management to store the relative disk address (ID) of the block retrieved 
by the READ macro, or of the next block — the two forms of the macro make different 
returns — you would specify the IDLOC keyword parameter of the DTF declarative macro 
(15.6.7). The form in which the ID is returned to you is governed by your specificaton of 
another DTF keyword parameter, RELATIVE, which you might also review (15.6.24). The 
uses of the IDLOC keyword parameter are further developed in what follows. 


OS/3 data management supports the READ macro only for DTFNI files or for DTFDA files. 


) 


es 
es, 
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15.7.14.1. Random Retrieval of Records ‘by Relative Disk Address (READ, ID) 


In order to use the READ,ID form of the READ macro to retrieve a specific record by its 
relative disk address, or ID, you have a number of keyword parameters in the DTFDA or 
DTFNI declarative macro to consider. First of all, recall the uses of the IOAREA1 and 
lOREG keyword parameters (the latter is used with the DTFNI macro only) to specify the 
main storage address into which the block that contains the record will be read (15.6.10 
and 15.6.11). You will also need to use the SEEKADR keyword parameter (15.6.26) to 
specify the 4-byte field in your program into which you will place the relative disk address 
of the record you want retrieved (which must always be greater than zero), and you must 
give notice to data management that you will.be using the READ,ID form of the macro, by 
specifying the READ=YES keyword parameter. in the DTF (15.6. 18).. Both the key of the 
block (if a key exists) and all data the block contains will always be read in. The form in 
which you provide the relative ID of the desired record must be the same as you specify 
with the RELATIVE keyword parameter. 


Further, if you need data management to return to you the ID of the next block in the file 
or partition after you issue the READ,ID form of the macro, you would specify the /ocation 
to which the ID is to be returned by the IDLOC keyword parameter (15.6.7). Finally, recall 
that the form in which the ID is returned has been specified by means of the RELATIVE 
keyword parameter (15.6.22). 


When the logical record you want retrieved by ID from a DTFNI file lies within a block of 
records retrieved, data management reads the entire block into your I/O area. After your 
execution of the mandatory WAITF macro, data management returns the displacement of 
the desired record into the block (measured in hexadecimal bytes) to the DTF file table, 
right-justified in a 2-byte field designated as filenameD. You may address this field by 
concatenating the character “‘D” to your 7-character file name. To retrieve subsequent 
records contained in the same block, you may issue successive GET macros in the 2- 
parameter form to specify the work area into which data management is to move the 
current record (15.7.12). An important point here is that you must know the structure of 
your blocks: there is no end-of-block indication provided by data management to prevent 
you from going past the last record in a block you are processing in this way. A GET macro 
issued after you have processed the last record in a block causes the entire next block to 
be read in from the DTFNI file, and the first record from it to be moved to the specified 
work area. 


The format of the READ,ID form of the READ macro is: 


filename ) , ID 
(1) 
1 





OPERAND 





A OPERATION A 
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‘Positional Parameter 1: 


filename 
Is the label in your program of the DTFDA or DTFNI declarative macro that 
defines the randomly, processed file from which you are retrieving records. 


(1) or 
‘ae that you have preloaded register 1 with the address of the DTF file 
table. | 


Positional Parameter 2: 


1D 


Specifies that a search is to be ‘made for a. record with an ID matching the 


relative disk address you have presented to data management, via the field 
| spécified in the SEEKADR keyword parameter of the DTF macro, in the form you 
. have specified with the. RELATIVE keyword parameter. | 


form 
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15.7.14.2. Direct Retrieval and Updating of Input Blocks by Key (READ, KEY) 


You will use the READ, KEY form of the READ macro when you want to retrieve blocks by 
a search on key from input files defined ‘by the DTFDA macro (15. 5.2) or randomly 
processed files defined by the DTFNI macro (15.5.3). It is this form of the READ macro that 
is also used, in combination with the WRITE,KEY form of the WRITE macro, for updating a 
randomly processed disk file (15. 7. 11. 5). 


You have ¢ a ‘number of points to consider when you are using the READ, KEY macro; ‘these 
involve several’ keyword parameters in the DTF. First of all, in order that data management ; 
may set up the DTF file ‘table properly for this macro, you must specify the READKEY © 
keyword parameter. To guide the search, you must provide both’a search argument and a 
starting point. With the KEYARG keyword, you ‘specify’ the key that i is to be matched by the 
key of the block you want retrieved (15.6.12); with the’ relative disk address that you place t 
in the 4-byte field, whose label you specify with the SEEKADR keyword (15.6.24), you 
supply the starting point of the search. As. to its end point, if you want the search to 
continue past the end of the current track to the end of the current cylinder, you specify 
the SRCHM keyword parame en otherwise, the search ends at the end of the track 
(15:6:26), Bi. oe 


Remember that the relative disk address you supply to data management must be in the 
form (relative track or relative record) that you. selected when you specified the RELATIVE 
keyword parameter (15.6.22): the same form is used by data management when it makes 
the return of the relative disk address of the retrieved block to the 4-byte field whose label 
you speciied with the IDLOC eee oe 6. a 


If the. search is Successtul: data. ‘oagagement moves the entire block to your VO. nutter: 
including the key. Thus; the length of IOAREA1 (and of IOAREA2,, if this is a DTFNI file and. 
you have specified double- -buffering)..must accommodate the length. of the key, as well as. 
the length of your data record, If this is a DTFNI file containing variable- length blocked 
records, you have not only the KEYLEN specification and the block descriptor word (BDW) 
to keep in mind, but also the record descriptor words (RDWs) that precede each logical 
record. In a DTFDA file, you. may not specify either of the blocked record formats, :but a 
variable-length record in this type of file is also._preceded by a BDW. and an RDW, exactly | 
as the variable, unblocked record is in the DTFNI file. A glance back at Figure 14—4 in the 
preceding section will help you visualize what is in your I/O area when the READ,KEY 
macro completes a successful search. Note that both the BDW and each RDW are four 
bytes long. 
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The data portion of a fixed, unblocked record from a DTFDA or DTFNI file begins at a 
displacement into your I/O area that is equal to your KEYLEN specification; the same is 
true of the first of your fixed-length logical records in the blocked format in DTFNI files; the 
succeeding records begin at intervals equal to your RECSIZE specification (15.6.21). When 
you have variable, unblocked records in either file, the first (or only) data portion is found 
at a displacement that is eight bytes longer than your KEYLEN specification; the 
displacement of each succeeding variable record in a blocked DTFNI file may be calculated | 
by adding in the contents of the first two bytes of the RDW for the record preceding it. 

Figure 14—4 shows these relationships, which you must use in accessing your logical 
records from a block retrieved by the READ, KEY macro after a successful. search. 


If the search is unsuccessful, data management first sets the record not found flag (byte 1, 

bit 3) in filenameC and.either the end of track (byte 1, bit 6) or both this flag and the end. 
of cylinder flag (byte ‘1, bit 7),. depending on whether or not you have specified 7 
SRCHM=YES in the DTF. Data Management then branches to your error. routine. (or 
returns control to you inline if you have no error routine specified). (Refer to Appendix B). 

Your error routine should check for these bits and provide action that is appropriate for 
your. application; otherwise, if you accept error returns inline, you should test for these 
flags after each issue of the READ, KEY macro. 


The format of the READ,KEY form of the READ macro is: 














AOPERATION A OPERAND 








( filename ) , KEY 
a 
| 1 ai? ‘ 


Here, the second positional parameter, KEY, specifies that data management will search 
for a block that has a key matching the one you have placed in ‘the location in your 
program specified by the KEYARG keyword parameter. The:search begins at the relative — 
disk address you have placed in the location defined by the keyword parameter SEEKADR 
and continues to the end of the one track, unless you have specified the SRCHM keyword ‘ 
parameter. : . 


The I/O area into which data is read will contain both the key and the data portions of the 
block read; data amanagermont moves the: key to the 70 buffer. . 
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15.7.15. Controlling Disk Head Movement to a Track (CNTRL) 


The CNTRL imperative macro gives you a means by which you may overlap disk head 
movement with the processing of your records. While it may be used when you are 
processing files. defined by the DTFDA, DTFSD,. or DTFNI. macros, the CNTRL macro is 
perhaps most useful for achieving some increase in throughput when you are sequentially 
processing files on.a shareable disk volume. (A shared volume is one. that may ,be 
accessed by more than one user program in a multiprogramming environment at your 
installation. It is described in the device assignment set by a VOL job control statement 
which has ‘ ‘s” as its second pestnonal parameter.) | 


When you issue the CNTRL macro to a DTFSD file, data management. issues a seek 
command that positions the disk head to the track you are Currently. processing. When you | 
are processing a DTFDA or DTFNI file, on the other hand, you may issue the CNTRL macro - 
to reposition the disk head to a new relative track address, which you place in the location 
specified by the SEEKADR keyword parameter of your DTF (15.6.26). 


When your program and another are sharing the same disk volume, issuing CNTRL may 
increase your throughput by positioning the disk head to the specified track while you are 
processing your records. Any CNTRL macro you issue to a blocked file is ignored, and data 
management will wait until the block is finished. (Of course, this feature protects you from 
interrupting your own block processing prematurely, as well.) 


When there is no problem of seek contention among programs (as when you are 
processing a nonshared volume), using the CNTRL macro may still increase your 
throughput and save you overall processing time. If you move the new current track 
address into the location specified by SEEKADR after successful completion of a READ or 
WRITE operation, for example, and then issue the CNTRL macro before you execute your 
other record processing instructions, the disk head is repositioned during the time you are 
processing, and data management can more promptly execute the next input or output 
imperative macro you issue. 


It should be clear from the foregoing discussion what the position of the WAITF macro 
must be that you will always issue after a READ or WRITE macro to randomly processed 
files (15.7.16): it must follow this macro and precede the CNTRL macro. To prevent you 
from repositioning the disk head before you learned of an incomplete input/output 
operation, data management will set the WA/7F required flag (byte O, bit 7 of filenameC) 
after determining that you have failed to issue the WAITF macro before executing the 
CNTRL imperative macro after a READ or WRITE macro. (The WAITF macro is not required 
after the CNTRL macro; the CNTRL macro makes no return to the IDLOC field of your 
program.) 
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This is the format of the CNTRL macro used for processing all nonindexed disk files: 








A OPERATION A OPERAND 


( filename ) , SEEK 
~ ¢< (1) . 
aT : 









The - second > positional parameter, SEEK, is always required; it specifies that data 


management will issue a seek command to the disk head, positioning it for DIFSD files to 


the current track or, for DTFDA or DTFNI files, to the relative track address contained in 


the 4-byte location whose label you have specified with the SEEKADR keyword, parameter. 


(The address at this location should be’ given in the form Ott, where tt is the relative, track ; 


number and 0 is binary O; it must be left-justified in the SEEKADR field, and you must 


have specified RELATIVE=T in the DTF for the file.) In the first positional parameter, .. 
filename is the label in your program for the DTFSD, DTFDA, or DTFNI declarative macro — 
defining the file; abe Or | r indicates that you have preloaded register. 1 with the address of 


is of file table’ 


UP-8068 Rev. 4 SPERRY UNIVAC OS/3° 15-105 


BASIC DATA MANAGEMENT 
WAITF 


15.7.16. Waiting on Completion of I/O to Random Disk Files (WAITF) — 


When. you are randomly processing input or output disk files defined by the. DTFDA or 
DTFNI sebehictbe macros, using the WAITF. macro is a compulsory safety measure ‘to 
issue another imperative. You must issue the ‘WAITF macro following each. READ. macro 
(15.7.14) or WRITE macro (15:7.11) you execute, before you may issue a CNTRL macro or 
another READ or WRITE macro for the same > file or Pecunlen:. The WAITE macro is not 


eneauined pollowing: the ie macro. 


When data management detects that you ‘have’ omitted this mandatory. macro, ‘it sets the 
WAITF réquited error flag (byte O, bit 7 of filenameC), and transfers control to your error 
routine, if-you have specified one, or to you. inline. 


The WAITF macro itself acts to check the completion of the data transfer you intended, 
and to set the appropriate status or error bits in the status code fields of filenameC. These 
bits you must always check after the execution of the WAITF macro — it is pointless - to 
anticipate the execution of the WAITF macro by checking filenameC immediately after you 
issue the READ or WRITE macro, although perfectly legitimate to check it when you are 
processing sequentially with the PUT macro and GET macro. (You do not use the WAITF 
macro with these sequential input/output processing imperatives.) 


The WAITF macro is not involved in the parity. checking of output. records: ‘this is 
performed as a Separate operation by data “management ‘only when you, Specify the 
optional VERIFY keyword parameter in your DTF (15.6.32). 


The format of the WAITF macro is simply: 





A OPERATION A OPERAND 


: filename oe 3 Ee | ‘ a | | z ts 


As elsewhere, filename is the label in your program of the DTFDA or randomly processed 
DTFNI declarative macro; (7) or 7 indicates that you have previously loaded general 
register 1 with the address of the corresponding DTF file table. 
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15.7.17. Accessing the Current Relative Block Address (NOTE) 


The NOTE macro, which you may use only with DTFNI files, is one of the extended 
capabilities OS/3 data management provides for processing nonindexed disk files. You 
may use it, whether you are processing DTFNI files randomly or sequentially, to access the 
relative address of the current block or ‘record. The NOTE macro is used in nepolanetion 
with the POINT macro (15, 7.18), where a coding example. is given. ‘3 


When you are processing sequentially, after issuing a GET or PUT macro, you use the 
NOTE macro to access the relative address of the current block and the displacement of 
the current record within this block. Because the addresses it returns are partition-relative, 
the NOTE macro relies upon your having. selected the partition previously by issuing the 
SETP macro (15.7.4) and, if you are working. within a subfile of this partition, having 
positioned yourself to this with the SETS macro o 7.5), 


For sequentially processed DTFNI files, the NOTE macro returns. the address to a 6 -byte 
field of the DTF file table in discontinuous binary in ie form: . 


Obbbdd 
where: 


_ Obbb. . 
. Is the number of the current block, relative to ‘the first block in 1 the file, 0 Hain 
binary O. ie ‘3 
dd f | | 
Is the displacement, measured in hexadecimal bytes, of the current record within 
that block. 


For randomly processed DTFNI files, you issue the NOTE macro following a READ or 
WRITE macro. The 6-byte address is in discontinuous binary, and the form of the address 
is governed by what you have specified for the RELATIVE keyword parameter in your DTF 
(15.6.22). If you have specified RELATIVE=R, the form is: 

rrrdd 


where: 


rrr 
Is the relative record address of the current block. 


dd 
Is binary O. 
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If you have specified RELATIVE=T, on the other hand, the address returned is in the form: | 
Ottrdd 
where: 


Ottr : 
Is the relative track address of the current block; ‘that is, r is the number of the . 
_ block on the relative track denoted by Ott, O being mene 0. 


Again, is binary 0. 
You ‘need to use the SETP and SETS macros for randomly processed files. alee. as 


mentioned in the previous paragraph, to pre-position yourself to the correct subfile of the. : 
correct partition. . 


The NOTE macro returns the address you. have specified to.a 6- byte field. in the DTFNI or 
DPCA file table that you address by concatenating the character ‘’B’’ to your 7- character | 


filename or partition name. ‘It is important to remember that. you must address this field as 


tilenameB whether you are processing the first partition (PCA1) of a partitioned DTFNI file 
or are processing a nonpartitioned file. It is only when you are working in the other . 
partitions. (PCA2 through PCA7), that you. address this field as perationgame’, 


This is the form of the NOTE macro:. 











“A OPERATIONA ~“OPERAND 











filename : : 
(1) 
1 ee 


Positional Parameter 1: 


filename | 
Is the label in your program of the corresponding DTFNI macroinstruction. The 
partition name is never used. 


(1) or 1 | 
Indicates that you have preloaded register 1 with the address of the DTFNI file 
table. 


Remember that all returned addresses are partition-relative; you must issue the 
appropriate SETP/SETS macros before issuing the NOTE macro (15.7.4 and 15.7.5). — 
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POINT. « - 


15.7.18. Positioning a File or Partition to a Relative Block Address (POINT) 


The POINT imperative macro is your means of randomly positioning a sequentially 
processed DTENI file or partition toa relative block’ address. This address | ‘may ‘be obtained, 
for example, via the NOTE macro just described (15. 7.17). Like NOTE, the POINT macro is 
a useful extension of capabilities (OS/3 data management provides for processing your 
DTFNI files; it is not supported for files you define by the DTFDA or DTFSD macros. 
Another similarity to the NOTE macro is that the POINT macro also relies on you to have 
selected your partition via the SETP macro (15.7.4) before you issue it. A third similarity is _ 


that the form’ ‘of the relative block address used d by the POINT macro is the same form the | 


NOTE macro uses. ~ 


When you issue the POINT macro for a sequentially processed DTFNI file, data . 
management, modifies the current. partition- -relative block address and block displacement _ 
that it maintains in the DTF file table (or in the DPCA Partition table; if you are processing ms 
ina Partition), you. are “Subsequently processing from. the new address. at 


An important. point ‘to remember is that the POINT macro is effective only’ sO long as you. 
continue to usé the GET and PUT macros in your subsequent processing of the’ file or ~ 
partition. If you subsequently issue a READ or WRITE macro (which would be quite. 

legitimate, for these are DTFNI files), these macros cause the current partition- -rélative 
block address to be modified by the relative track or record address you will have supplied 
to data management in. the area specified by the SEEKADR. keyword parameter of your 
DTF (15.6:24). There ‘is noerror: indication returned‘to you’ when this oEcda yor must ie 
upon yourself to keep this point in mind. sae 2 


This is the format of the POINT macro: 














OPERAND 


filename ) , ( address-field . 
SAY. 2, 0 -§ (0), ae (eee 


A OPERATION A 











Positional Parameter 1: 


filename 
_Is the label in, Your Program. of the comesponcing DTFNI macroinstruction.. 


(1) or 4 
Indicates that you have preloaded register 1 with the address of the DTFNI file 
table. 


ee, 
; } 
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Positonal Parameter 2: 


- address-field 
Is the label of a 6- oer field (Obbbdd) | in your program containing ‘the relative 
block address. and displacement of the record within the block. The relative block 
address portion (Obbb) is right-justified in the first four bytes, and the record 
displacement (dd) is right-justified in the second two. 


(0) or-O 
Indicates that you have» preloaded ee 0 with the address of the 6- oe 
address field. : ee ee er ve det 


Remember that, when you are processing athicn: a partition, or a a cubtilé of a saniion, you 
must have preselected these by issuing the appropriate SETP and SETS macros (15:7.4 
and 15.7.5). For this reason, the partition name is never used san operand of the PONT 
macro. cays 
The coding example that follows’shows the use’ of a NOTE macro to accéss the current 
relative address of a sequentially processed output: file, FILE1, whenever a record 
containing a:desired value, ‘VALU’, in its first four positions is encountered. This address 
is then used by a POINT macro. in a selective input or updating of FILE1, in what amounts 
to random Ere ina PSE gHental file. FEES is _used ¢ as an index t to ) FILE for this 
Processing DF te Res 


Exa mple: 


LABEL | AOPERATIONA ; OPERAND A 


7 STEP DREN | |BLLE: PELE sti tiviityasits 
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Example (cont): 


LABEL, | POPERATIONS.- | _ OPERAND . A 


TEP 21 


G 
y 
m 
z 


DLE ELL EZ... 


FILEZ) WoORKIA 


b. a 
T. FILE |), WaRKAz 
2 FLLEl 4s SRA 


LUE 5WORKAL 1. " porte oe dea 





Sot Ps to 
G iN tod v 
-P ie. im © Im 
bit eT 
rEEET Bee eS BE 


NO 


\ a 
: , 2 : 


Re Ls VAIL, 7 | -_ 


1. FILE1. and FILE2, both DTFNI files, are opened for. sequential OUIpOE procesemnd: 
wee Racor output to FILE1. is dated for desea: value, VALU". 
3. NOTE macro is issued when "VALU! found; ‘relative address is returned to 
filenameB. 
4. Relative address found by NOTE is output t to  FILE2, which. will serve as an index 
in STEP2. — a . : 
5. FILE1. is reopened” for sean FILE2 for ‘input processing (assume file 
processing directions have been reset). . . 
6. ‘Record retrieved from FILE2 is the address of a fecoid in FILET containing 
MEE: ie . 
7 POINT macro is ‘issued to position, FILE1 to addtexs obtained. in ie ae: 
8. Sequential processing continues in FILE1 from position set in 7. 
9. Definition of the desired value, normally located outside of. executable code. 
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15.8. ERROR AND EXCEPTION HANDLING 


15.8.1. FilenameC 


When certain errors or exceptions to file processing performance are detected by OS/3 
data management, it will make appropriate entries in specific fields of the DTF file table, 
which your program may address in order to learn of these conditions and take the proper 
course of action on regaining control. One such field is filenameC (in the nonindexed file 
processor system a 4-byte field), which you may access by concatenating the character 
“C" to your 7-character logical filename. 


A point to remember when you are processing the partitions of a DTFNI file is that, just as 
your ERROR routine is a file-relative specification and belongs in your DTFNI declarative 
macro (not in the DPCA declarative macro defining the partition), you do not have a field 
for error flags in the partition control appendage established in the DPCA macro. That is, 
there is no “‘partition-nameC”; error and status flags set during processing of partitions 
are set in the field of the DTFNI file table and are accessed, therefore, as filenameC. 


Most of the error and status flags have already been discussed in preceding paragraphs; 
refer to Table B—3 for the meanings of the bits in filenameC of the DIFSD, DTFDA, and 
DTFNI filetables that are set to binary 1 by OS/3 data management for certain error and 
exception conditions. 


Not all of the status flags represent conditions causing transfer of control to your error 
routine. Some of these must be tested for /n/ine in your program if you want to act upon 
them. 
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16. System Resource Control 


16.1. DEVICE ALLOCATION AND FILE ASSIGNMENT 


In 0S/3, the supervisor sna job serial have the Sesartial responsibility for reserving 
main storage and allocating peripheral devices for jobs that appear in the control stream 
and make their needs known through job control statements following the JOB statement. 
Of these statements, DVC, VOL, EXT, LBL, and LFD are essential for providing information 
relating to your files. With proper use of these statements you may reserve peripheral 
devices and identify and assign to your Progam the files yeu Dave: on them or will place 
on them. 


16.1.1. Use of Job Control Statements 


Every file that you intend to reference in your program must be represented in the job 
control stream by a set of control statements, called the device assignment set, which 
contains at least a DVC statement followed by an LFD statement. Between these basic two, 
you will need to insert as many as six other statements for your magnetic tape and disk 


files: the VOL, EXT, LBL, LCB, VFB, and DD statements. The device assignment set specifies 


the relationships between your files or volumes and the peripheral devices; there is one set 
for each file. Following is a short summary of the functions of these statements; all are 
described in the job control user guide, UP-8065 (current version): 

= The DVC statement assigns peripnen BevICES to your job. 


= The VOL statement specifies the magnetic tape or disk file volumes to be accessed by 
the job. 


= The EXT statement establishes new disk files or extends existing files on disk. 


= The LCB statement specifies and loads to the printer a unique load code buffer that 
overrides the LCB set at SYSGEN time. 


= The VFB statement specifies and loads a | unique vertical format buffer that overrides 
the VFB set at SYSGEN time. =e ; 


= The DD statement modifies fields within the DTF file table at run time and avoids 
recompiling DTF’s when changes in DTF specifications are required. 
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= The LBL statement supplies label information for magnetic tape or disk files. 
= The LFD statement identifies the file control block for each file used in your job. 


Card and paper tape files use only the DVC and LFD statements and optionally the DD 
statement. The printer always uses the DVC and LFD statements and optionally the LCB, 
VFB, and DD statements. 


16.1.2. Sample Device Assignment Set 


Following is an example of a set of control statements that you would use for reserving 
space for a sequential disk file that is to be created: 


LABEL AOPERATIONA ._... OPERAND : A 


10 
DIC, Blo ta 
1 ET, Al ICs 5:55 VG hOhsrs | 

LBiL TINV.ENT les ASTER, IFT LE,’ 
/, LiF/D LINVINTRY1 II 


This device assignment set will cause modification of the volume table of contents (VTOC) 
of disk pack 124365 to show that a sequential file called ‘INVENTORY MASTER FILE’ 
exists, and that the space reserved for it occupies a specific position on the pack. OS/3 job 
control will also note that your program will address this file as ‘INVNTRY’ (its: logical 
name), and that space for one extent entry in the prologue area will suffice. To start with, 
the file will be assigned 10 cylinders of contiguous space. When this space is exhausted, 
you desire automatic extension, five cylinders at a time. ara ars 


NIX IS 


> 


i 
(Coc 


When space for only one extent in the prologue area is specified, no dynamic extension 
can take place. 


For a program that will subsequently operate on this file, you would use the same set of 
job control statements, except that you would omit the EXT statement. If you want to 
recreate a file (for example, if an error occurred during your first attempt to create it), you 
may use the INIT positional parameter of the LFD statement. This parameter has the same 
effect as scratching the file and reallocating it to the same area as it previously occupied 
on disk. 


16.1.3. Job Control Deallocation Statement (SCR) 


The OS/3 job control language also provides an SCR statement that you may use to 
deallocate (scratch) a file from a disk pack. When you use this statement, you must use an 
_LFD name that is the same as the one you have used for the file in a preceding valid 
device assignment set (DVC-LFD). The SCR statement. will deallocate the file and its 
extents before the program named in the next EXEC statement in the control stream is 
executed; therefore, you may use it to free disk space needed for a subsequent job or job 
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step. (The disk space management facilities of the OS/3 supervisor also include an 


imperative. macro, SCRTCH, that provides similar functions and-is used for dynamic 
deallocation (16.3).) . 


16.1.4. Using the File Lock Feature 

The OS/3 file lock feature allows you to control the sharability of a file while you are 
using it. Sharability control only applies to lockable files. To use the file lock. feature, 
proceed as follows: 


: Step 1 
At system generation, you specify the FILELOCK parameter to indicate which files are 
lockable. 
= Step 2 


In your file definition (within your BAL program) and in the device assignment set for 
the file (regardless of the program type), you specify your read/write requirements 
and indicate whether other jobs or tasks within a job can share the file. 
In the following paragraphs we will describe how to indicate which files canbe locked and 
how to set the various degrees of sharability. 


16.1.4.1. Indicating Which Files are Lockable 


You. indicate ‘which files are lockable by using the FILELOCK parameter in. the SUPGEN 


section of. the parameter processor at system generation time. gic 


If you dnaeee FILELOCK=NO or omit the parameter, only the system files prefixed with 
SYS are lockable. No user files can be locked. 


if you choose FILELOCK=YES, all system files (prefixed with SYS) and. all files prefixed 


_with $LOKO1-$LOK99 are lockable. 


If you choose FILELOCK=SHARE, all files are lockable. 


16.1.4.2. Setting File Locks for Data Files in BAL Programs 


After you specify which files are lockable, you specify the degree of sharability for each of 


these files. 


If you choose FILELOCK=YES at system generation time, you can lock any file whose 
filename you prefixed with $LOKO1-SLOK99 in the // LBL job control statement in the 
device assignment set. If you do nothing more, any prefixed file will be exclusively locked 
when it is opened during the execution of your program. You have exclusive use of the 
file. You can read, update, and add to the file. No other user can open the file until you 
close it. 
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If you choose FILELOCK=SHARE at system generation time, you can lock all of your files. 
If you do nothing more, each file will be exclusively locked when it is opened during the 
execution of your program. You have exclusive use of the file. You can read, update, and 
add to the file. No other user can access the file until you close it. 


In both cases (FILELOCK=YES or FILELOCK=SHARE specified at system generation), you 
can override this lock by specifying one of the options of the ACCESS parameter or by 
specifying the LOCK=NO parameter in the DTF macroinstruction for a file. (See 11.4.1 and 
11.4.11.) 


You can also override this lock at program execution time in two ways. The first way is to 
include a // DD job control statement that specifies one of the ACCESS parameter options 
in your device assignment set. The second is to prefix the filename with an asterisk (*) in the 
// LFD job control statement in the device assignment'set. This will cause a read-only lock 
to be applied to the file; that is, you can only read from the file and all other users can only 
read from the file. 


AO 


To set file locks on SA T files, see the supervisor user guide, UP-8075 (current version). 


16.1.4.3. Setting File Locks for Data Files in Non-BAL Programs | 


After you specify which files are lockable, you specify the degree of sharability for each of 
these files. 


_If you choose FILELOCK=YES at system generation time, you can lock any file whose 
filename is prefixed with $LOKO1 -$LOKQ9 in the // LBL job control statement in the device 
assignment set. If you do nothing more, any prefixed file will be exclusively locked when it is 
opened in your program. You have exclusive use of the file. You can read, update, or add to 
the file. No other user can access the file until you close it. 


If you choose FILELOCK=SHARE at system generation time, you can lock all of your files. 
lf you do nothing more, each file will be exclusively locked when it is opened in your 
program. You have exclusive use of the file. You can read, update, or add to the file. No 
other user can access the file until you close it. 


In both cases (FILELOCK=YES or FILELOCK=SHARE specified at system generation) you 
can override this lock at program execution time. There are two ways to do this. The first 
way is to include a // DD job control statement that specifies one of the ACCESS parameter 
options in the device assignment set. The second is to prefix the filename with an asterisk (* 
_) in the // LFD job control statement in the device assignment set. This will cause a read- 
only lock to be applied to the file; that is, you can only read from the file and all other users 
can only read from the file. 
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16.1.4.4. File Lock Feature Summary 


Table 16-1 summarizes the data management file lock feature. Remember, before using 
this feature, you indicated which files are lockable at system generation time through the 
FILELOCK keyword parameter. Once again, the available options are: 


FILELOCK=NO indicates that only the system files prefixed with $Y$ are lockable. No 
user files can be locked. 


FILELOCK=YES indicates that all system files (prefixed with $Y$) and all files prefixed 
with $LOKO1-$LOK99 are lockable. 


FILELOCK=SHARE indicates that all files are lockable. 


Table 16—1. File Lock Summary 


~ LOCK=NO@not This DTF: read use/ | ACCESS=EXC © This DTF: read use/ 
specified update use/add use update use/add use 

Other jobs: no Other jobs: no 

access access 













































LOCK=NO® This DTF: read use 
Other jobs: read 


use 






ACCESS=EXCR This DTF: read use/ 
update use/add use 
Other jobs: read 

use (ACCESS=SRD 


specified for other jobs) 





ACCESS=SRDO ® This DTF: read use 
Other jobs: read 
use (ACCESS=SRD 
or SRDO specified for 


‘other jobs) 


This DTF: read use 
Other jobs: read 
use/update use/ 
add use (ACCESS=EXCR, 
SRD, or SRDO specified 
for other jobs) 


ACCESS=SRD 










NOTES: 


@) LOCK=NO not specified and ACCESS=EXC are functionally equivalent. 


(2 LOCK=NO and ACCESS=SRDO are functionally equivalent. 
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Remember, files are locked based upon the physical file name or $LOKnn prefix for the 
name that you specified in the // LBL job control statement of the device assignment set. 
The volume serial number is not used. Since this is the case, you should use a unique 
physical file name or $LOKnn prefix to differentiate between unrelated files or file sets on 
different volumes. a 


If you specify the same physical file name or $LOKnn prefix for unrelated files, you risk 
having files locked out unnecessarily when the ACCESS options are not compatible. For 
example, assume that files A and B are unrelated and are on different volumes. Also 
assume that these files have the same physical file name on the // LBL job control 
statement in their respective device assignment sets. If file A is lockable and has been — 
opened for exclusive use with JOB1, no other job can open file B because its physical file 
name has already been locked to JOB1 even though file A is an unrelated/different file. 
Using unique file names prevents this from happening. 
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16.2. RENAMING A DISK FILE (RENAME) 


Neither OS/3 job control nor data management provides a means for renaming an existing 
disk file. If you need to change the name of one of your files (as recorded in the 44-byte 
file ID field of the format 1 label on disk), you must do it dynamically within your program, 
using the RENAME imperative macroinstruction provided by the disk space management 
facilities of the OS/3 supervisor. Note that you should not issue the RENAME macro to a 
file that is currrently open. 


Function: 


The disk space management macro RENAME allows you to rename any disk file but a 
system file. By specifying the new 44-byte file identifier you want used, the 7-byte 
logical file name, and the volume sequence number of the volume on which the file 
resides, you cause the new file identifier to replace the old file ID in the format 1 
label of the VTOC. (The 7-byte logical file name is the same as that appearing as the 
first operand of an LFD job control statement for the file and in the label field of the 
corresponding data management DTF declarative macro.) 


Format: f 





OPERAND 


tas oc [,vol-seq-no] 
(1) “Ur 





AOPERATION A 
















[name] RENAME 


Positional Parameter 1: 


param-list 
Specifies the address of a parameter list containing a 7-byte filename (as listed 
on the LFD job control statement and in the label field of the corresponding DTF 
macro) and a 44-byte new file identifier. The parameter list is a 52-byte 
character string, the first eight bytes of which contain the LFD-name of the file, 
left-justified; the last 44 bytes contain the new file /D, also left-justified. 


(1) 
Indicates that register 1 has been preloaded with the address of the parameter 
list. 


Positional Parameter 2: 


error-addr 
Symbolic address to which control is transferred if an error is encountered. 


(r) 
Indicates that a register (2 through 12) has been preloaded with the error 
address. 


PEI 


fem 
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Positional Parameter 3: 


vol-seq-no 
Specifies the volume of a multivolume file to be renamed. 


If omitted, the value 1 is assumed. 


Examples: 


LABEL JOOEERATIONDS OPERAND | | - oe ae Se 
16 —_ 


L) 1.2 


RENAME PLL 


rh 
| im_| 
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16.3. DYNAMIC DEALLOCATION OF A DISK FILE (SCRTCH) 


Function: 

The disk space management macro SCRTCH enables you to deallocate any disk file 
but a system file, making the space available for future use. After validating your 
request, the SCRTCH macro removes the definition of the space or extents from the 
format 1 or format 3 labels and updates the format 5 label in the VTOC. The extent of 

_the newly available freed space is inserted .in the correct. position in the format 5 
record, where available extents are described in ascending sequence of relative track 
addresses. If you deallocate your file, the SCRTCH macro deletes all format 1, 2, and 
3 labels from the VTOC and replaces them with format O labels. Note that you should 
not issue the SCRTCH macro to a file that is currently open. 


Three basic deallocation (scratch) functions are available to you: 
= ~=6deallocation of files by prefix; 


x deallocation of files by expiration date; and 


OO 


GOP, 


” complete deallocation of a file by file ID. 


To deallocate files by prefix, you place a 4-byte prefix in bytes 76—79 of the file 
control block (FCB) of the file in main storage and specify the PREFIX parameter; the 
SCRTCH macro searches the VTOC for files with file ID fields beginning with these 
four characters and deallocates each one matched. The prefix may not include the 
characters $Y$, so that it is not possible to you to scratch system files by mistake. But 
by this macro you may deallocate all your temporary work files with one call.on OS/3 
‘disk space management. 


To deallocate expired files, you specify the ALL parameter and include the expiration 
date in the 3-byte expiration date field of the FCB; the SCRTCH macro compares this 
with the expiration date in each format 1 label in the VTOC and deallocates all files 
with earlier expiration dates. 


To deallocate an entire file by the 44-byte file ID that is contained in the FCB, you 


either omit the second positional parameter altogether, or specify (O) and preload bits 
O through 7 of general register O with the hexadecimal code OO. 


aia 
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Format: 









LABEL... |. AOPERATION A. 





_OPERAND _ 






SCRTCH 


irgonmnes| Jo (] [forratr 


PREFIX 


’ Positional Parameter -1: 


FCB-name . 
- Specifies the symbolic address of the FCB in main storage. 


Bytes 


volume serial number 





:prefix,:or expiration date, or file ID. 


(see table below) 


et eR 


Bytes . Contents. 


O—5 Volume serial number (VSN) of ‘disk pack on which files to be 
deallocated reside 


~6—n One of the following: ne - 


a 4-byte prefix (may not contain $Y$); requires specification of 
PREFIX in positional parameter 2 


#  3-byte expiration date, in discontinuous binary in the form 
YDD (year, day, day), where Y ranges from O to 99 and DD 
ranges from 1 to 366; requires specification of ALL in 
positional parameter 2 


w# 44-byte file identification mame; requires omission of 
positional parameter 2 


(1) 
Indicates that you have preloaded general register 1 with the symbolic address of 
the FCB in main storage. 
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Positional Parameter 2: 


(0) 

Indicates that you have preloaded register O with a hexadecimal function code 

specifying the scratch operation desired, as follows: 

Function Code Interpretation 

00 Scratch entire file. 

82 Scratch all files of the volume whose expiration date is 
exceeded by the content of the 3-byte exp/ration-date field of 
the FCB. 

83 Scratch all files that have the 4-byte prefix contained in bytes 
76—79 of the FCB. 

ALL. | | : 
Specifies that all files of the specified volume with expired dates will be 
deallocated. 

PREFIX 


Specifies that all files of the specified volume whose file IDs begin with the 4- 
byte prefix placed in bytes 76—79 of the FCB are to be deallocated. 


If positional parameter 2 is omitted, the file specified by the 44-byte file ID i in the FCB 
is scratched. 


Positional Parameter 3: 


error-addr | 
Specifies the symbolic address of your error routine,.to which control will be 
transferred if an error is encountered. 


(r) 
Indicates that you have preloaded the specified register with the address of your 
error routine. Register O and 1 cannot be specified. | 


8802, 
< % 
\ 
ri 
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Examples: 


LABEL poeehanion® OPERAND A 
16 


Seren to MYFILIEs ALL, ERT 
Pee aaes ¢ haere 
atest. | berrclll meneLc CLO 


“1. This macro deallocates all files whose expiration dates are exceeded by the 
contents of the 3-byte expiration date field of the FCB whose symbolic address is 
MYFLE. Your error routines’ symbolic address is ERRXT. 


2. This macro scratches the file whose 44-byte file ID is contained in the FCB 
whose symbolic. address is TRIFLE. You have preloaded general register 10 with 
the address of your error routine. 


16.4. DISK SPACE MANAGEMENT AND THE VTOC 


We have discussed two disk space management routines that update the VTOC of a disk 
pack for you. All together, there are five OS/3 disk space management routines providing 
vital services for maintaining a correct VTOC on every disk pack. Two of these transients 
(ALLOC and EXTEND) you will not use directly because they are invoked automatically for 
you, when you need them, by OS/3 data management or job control; they are therefore 
not documented here but in the supervisor user guide, UP-8075 (current version). 


Because the disk space management routines provide efficient, completely automatic 
space accounting and maintenance, they relieve you of the burden of keeping precise track 
of the contents of your disk files. An understanding of the structure of the VTOC and the 
format of its label records is not essential to you as a data management user; however, 
Appendix D describes the VTOC in full detail for your information, and the disk space 
management macro OBTAIN is available for the rare occasions you will have to examine it 
from a program. 
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16.4.1. Retrieving :‘VTOC Information (OBTAIN) 

Function: | | 
The disk space management macro OBTAIN returns to you either the disk address or 
the contents of a specified VTOC format label record for a specified disk volume. You 
must specify a return buffer of a size appropriate for the information you want 
retrieved. | 


Format: 







OPERAND. . 


aa f error-addr | ae 
(1) SJ Ur) vis AOE 


A OPERATION A 













OBTAIN 


Positional Parameter 1: 


param-list 7 thin 20 the a | 
_Is the address of a 12-byte parameter list containing the following: 


Bytes O—7 7-byte logical filename (as listed in the LED Job control statement) 
Byte8 Hexadecimal code of the retrieval function to be performed on the 
=. aie VTOC of the disk volume whose volume Sequence number is 


specified by positional parameter 3 


: Code Function 


00 Return VOL1 disk address 

01 Return format 1 disk address 
02 Return format 2 disk address 
03 Return format 3 disk address 
04 Return format 4 disk address 
05 Return format 5 disk address 
06 Return format 6 disk address 


80 Return contents of VOL1 label 


UP-8068 Rev. 4 


Bytes 9—11 
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Code Function 


81 Return contents of format 1 label 
82 | Retuna contentsxot format 2 label 
83 Return contents of format 3 label 
84 Return contents of format 4 label 
85 Return contents of format 5 label 
._ 86. ~—_—s Return contents of format 6 label " 
oY Samael Return « contents of the label record that is located at the 


disk address that has been preigeeg” into the first viens 
of the return buffer. : 


Return buffer address. Specifies the address in main storage of a 


~return buffer. The OBTAIN macro places. the disk” address or the 


contents of the specified format label in the return buffer specified 


by this field. All disk addresses returned’ by the OBTAIN macro are 


stored in bytes O through 3 of this buffer, in the form O ccc hh rr, 


in discontinuous binary. If you specify function code 87, you must 


mei 


(1) 


store the disk address of the format label you want ‘retrieved in the 
same location in this buffer, in the same form and format. 


The size of your return buffer must be four bytes when you request 
the return of an address, 84 bytes when you request the contents 


_ of the VOL1 label, and 140 bytes when you eae the, contents of 
- a disk format label record. . 


Indicates that you have preloaded register 1 with the address of the parameter 


list. 


Positional Parameter 2: 


error-addr 


Symbolic address of your error routine, to which control is transferred when an 
error is encountered. 


(r) 


Indicates that you have preloaded the specified register with the address of your 
error routine. Registers O and 1 may not be specified. 
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Positional Parameter 3: 
vol-seq-no 
Specifies the volume sequence number of that volume of a multivolume file from 
which you want to retrieve VTOC information. 


If omitted, a value of 1 is assumed. 


Examples: 


LABEL AOPERATIONA OPERAND A 
1 6 - 


1 ye | 
lee era 22 
saree Veen 

of peas msec, me 


1. You . have preloaded register 1 with the address of your parameter list and 

| register 4 with the address of your error routine; you are retrieving information 
from the VTOC of the second volume of a multivolume file. 

2, | This example is seciang information from the VTOC of the first volume of a 


multivolume file; the error routine and parameter list are specified by their o~ 
symbolic addresses, ERRRTN and RECOVER1, respectively. J 4 
16.4.1.1. Retrieving Specific Format Label Items 


Once you have retrieved the desired format label with the OBTAIN macro, you may 
address a specific field by its individual label; these labels are shown in Appendix D. 


PART 5. PAPER TAPE FILES 


— 

ge 
Ry 

i 

2 


f 
i 
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17. Paper Tape Data Management 


17.1. GENERAL. 


This section describes OS/3 paper tape data management, a system that provides the 
basic assembly language (BAL) programmer with access at the logical-record level to the 
SPERRY UNIVAC 0920 Paper Tape Subsystem. The operational characteristics of the latter 
are outlined in Table A—6; for further information, however, refer to the 0920 paper tape 
subsystem programmer reference, UP-7998 (current version). 


After a brief discussion of the hardware and paper.tape itself, this section describes the 
effects of various character and record types on the modes of processing paper tape files 
and gives an overview of programming with paper tape data management. Following this 
overview, the four file processing imperative functions OPEN, CLOSE, GET, and PUT are 
explained, with a description of the means available to you as a BAL programmer in OS/3 
tof spererin the paper se data eee tan precess!9 modules with yeur own code: 


The matter of asinine: a paper dope file to “data. ar peconent using the pwc 
parameters of the DTFPT declarative macro to specify its characteristics and your 
requirements for processing it, is then presented in full detail, with a number of simple 
coding examples to clarify. the: use. of::shift code.scan tables and translation tables. The 
discussion of file definition closes with a description of data management error processing 
for paper tape files and the use of scan:‘and translation tables when processing paper 
pes in ASCII American: Nationa! sreneel’ Code: for Information| Interchange). 

This: Section “Poncludes with: ‘a few notes on nie compatibility of OS/ 3: with the solid tape 
data menegement: of other : ‘operating: systems. ; 


17.2. Pee AND PAPER TAPE CONSIDERATIONS 


The data management paper tape system in OS/3 is designed to be used with the 0920 
paper tape subsystem, which can be configured as a. paper.tape reader, a paper tape 
setae or a combined reader and punch. 

It is ‘aaportant to. note that wher the eeu is acing used @ asa combined reader and 
punch, there ‘are two separate paper tape paths:: Whereas reading and punching can take 
place at the same time in such a subsystem, they cannot take place in one pass on the 
same tape. Two different passes are necessary to read and punch on the same piece of 
paper tape, and in OS/3 the tape must be defined with a separate DTF for each such pass: 
once as an input file, once for output, using different file names. In addition, you require 
separate job control device assignment sets (of DVC-LFD statements). 
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As a reader, the 0920 paper tape subsystem can handle three different widths of tape: 
11/16, 7/8, and 1 inch. The subsystem can punch two widths: 11/16 and 1 inch. As to 
the number of tracks, or levels of tape characters, the subsystem can read or punch 5- 
level tape on the: 11/16-inch width and from 5 through 8 levels on the 1-inch width. 


The subsystem runs in two reading and punching modes: binary and character. In the 
binary mode, which is used only with 8-level (1-inch) tapes, there is a fixed, direct 
correspondence between bits in main storage and holes punched on the tape, that cannot 
be altered by rewiring the program connector board (17.2.1). 


In the character mode (also called standard, or nonbinary, mode) from 5- to 7-level tapes 
are read and punched; an even or odd parity signal may be punched on the tape and 
checked during reading. It is not transferred to main storage, but, if a parity error is 
detected (this is always done by the hardware), the most significant bit of the byte in main 
storage representing the character is set to 1. 


In addition, you may set up the program connector board to allow detection of a stop 
character (often called the ‘“‘wired stop character’’ because of the clip-on wires used), as 
well as a delete character. ee _ j 


17.2.1. The Program Connector Board 


For control, the 0920 paper tape subsystem uses the program connector, a printed circuit 

patch card which you set up with clip-on. wires for the specific tape you are reading or é 
punching. You will have much need of the program connector for processing in character baad 
mode, but it is bypassed completely for processing in binary mode: A short summary to 

highlight the procedure for wiring the program connector follows; for full details, consult 

the 0920 paper tape subsystem. programmer reference, UP-7998 (current version). . 


aa 


17.2.1.1. Wiring the Program Connector for the Tape Punch 


There are eight punch actuator circuits, each connected to a pin on the program connector: 
board. In addition, there is a pin on the board for each of the seven least significant bits of 
a byte in main storage, and two pins that generate odd or even parity signals, based on 
the content of all eight bits of the byte in main storage..You connect. the actuator pins to 
the main storage bit pins by the clip-on wires; any: actuator pin can be connected to any 
bit pin. You can connect either parity signal pin (the odd or the even) to one of the actuator 
pins, or you can ground the unused actuator OMe together so that Lnotaing is panenee in 
their tracks. 


17.2.1. 2. Wiring the Program Connector for the: Tape Reader 


A pin on the program connector is connected to each of the eight Shotediodes in the road 
station of the device; there are also pins for each of the seven least significant bits of a 
byte in main storage, and two pins connected to reader circuits neh ee odd or even 
BOrIty, ee a ie G38 ‘a & — . 3 os 
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You connect seven of the photodiode pins to any of the seven bit pins; any of the bit pins 
can be grounded so that the associated bit in main storage is always zero. You may also 
connect one of the two parity-check circuit pins to any one of the photodiode pins, or the 
parity- -check Bins: can De: so connected that no parity checking is 5 gone: 


The reader: section of the program connector also allows. you to - gpecify one Halete 
character. and:one stop character for detection by the hardware when it is reading in 
character mode; however, in the binary mode, it cannot detect these characters. Therefore, 
if you. need ‘to delete characters from your input records in binary mode, or if ‘your 
application requires additional delete characters, remember that you must specify these as 
software deletes in your program, rans ane SCAN > ails parameter of the” aaa 
declarative macro ie 5.3. 1). . 


17.2.2. Paper Tape Leader 


If the optional. tape spooler is used with the 0920 paper tape subsystem, a tape leader at 
least three feet long must precede the first data character to be read on the tape. In the 
binary mode, the leader must consist only of nu// characters; in the character mode, you 
may use either null or delete characters. If the reader Bepocier is not. Heed, the paper tape 
leader may be as short as two inches: 


17.2.3. Paper Tape Trailer 

When you are using the 0920 paper tape subsystem, you receive an indication of broken 
tape if there are data characters under the read photodiodes when the end-of-tape switch 
is activated. A false indication of broken tape, therefore, results when the end of an 
unbroken tape goes by while the last of the data characters: are still being read. To prevent 
this false error indication from being given, you must follow the last data character on an 
input tape with a ‘tape trailer’ at least. 12 inches (120° characters) long; there must be 
nondata characters. In the binary mode, the trailer must consist only of null characters; in 
me eharaeter mou: you: may. use. null or delete characters. f 


nigufe VW7-1 isa schematic diagram c of a 1 paper tape file with its leader and trailer. 
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LEGEND: 


L Tepe leader. Immediately pracedes the first data character o on paper tape and comprises only null characters in PoInaAy 
‘mode; may comprise null or delete characters in character (standard) mode. Must be at least three feet (360 
characters) long if the optional tape spooler is used on 0920 paper tape subsystem; otherwise ‘needs to be'no more 

than two inches (20 characters) long. 


T Tape trailer. Immediately follows the last data character on paper tape; must be at least 12 inches (120 characters) 
long to prevent false error indication of broken tape. Comprises only null characters in binary mode; may comprise null 
or delete characters in character mode. 


D Data file. In character mode, the format of data records may be either fixed, unblocked or undefined (that is, records 
are of various lengths). The only record format used in binary is fixed, unblocked. 


Figure 17—17. Tape Leader, Paper Tape Data File, and Tape Trailer 
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17.3. CHARACTER AND BECORD TYPES ON: PAPER TAPE 


Before logking into ike way your sae is Y organiied. on sunched: paper. tape and appears to 
data management and to your. program, consider the uses of several character types 
already mentioned, but not explainted so far: the null character, the delete character, and 
the. end-of-record stop. These are part of a class of characters, selected by convention or 
arbitarily from among all the possible patterns that may be punched in one character's 
space on tape, different from the rest only in that they are not: used to represent data. 
They are sometimes called :contro/ characters, but, on the other hand, they may represent 
the absence of data or serve as information separators. or delimiters to format your data. 
They: may serve merely to fill space on tape-as a tape leader as trailer. One of them may 
be used to obliterate unwanted or erroneous data characters or other nondata characters. 
Characters from this class may indeed be used to control communications or devices 
(here, for example, the 0920 paper tape subsystem itself), and the term control characters 
is then appropriate. 


An: important realization is that each tape code you must assign to one of these characters 
reduces by one the subset of possibilities you may. use to:represent your data. When you 
are processing in character, or standard, mode, however, this limitation is not as serious 
as it may seem: data management's letter/figure -shifting capability allows you to 
represent more than one set of charcters in the same set of hole patterns punched on 
tape. 


17.3.1. Null, Delete, and seep epatacters 
s.. Null Character 


The null Giaracten. is ssfannsesnted on ape: iy: the aheeHiee: on: any: cunahoes in the 
information levels (tracks); only the feed (or:sprocket) hole is punched. To:-punch the 
tape code for the:null character, you place’ the hexadecimal value OO — a standard 
convention in both ASCII and. EBCDIC. processing — in your |/O area: You may use 
the null character (or the delete) in the paper tape leader and trailer when you are 
processing in character mode (MODE=STD), but you must use on/y the null for these 
purposes in binary’ mode (17.2.2, 17.2.3). Similarly, you must use: only the null 
character to represent the optional /nterrecord gap in binary a aneder the 
,Mlelete, character may be. usee: instead, in character mode (17.3. 4). 


~ When you start to read paper tape, the subsystem foods tape until it comes. to the 
first character that is not a null (or a delete); it then, beginning. with this character, 
starts to transfer characters into main storage. For this reason, you must never use 
--the null as the first character of the first record on a tape; if you do, all subsequent 
record lengths are off by one byte. In binary mode, once the transfer of data has 
begun, all subsequent null characters are read into main storage, as binary O’s 
(hexadecimal 00), and, whatever these represent in your input file, you must program 
~. to deal with them. In character . ‘mode, on the other hand ea nulls are 
never transferred into. main storage. Z . 


oem, 


“caer 
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Delete Characters 


You may represent a delete character on tape by any of the hole patterns available for 
you to punch, although the standard ASCII delete character isa punch in each of the 
seven data tracks (17.5.10): The practice of punching a hole in each track or data 


level to represent a delete character: facilitates one of ‘the main uses of the character: 


to cancel or obliterate unwanted data in a'record. There are, however, two types of 


‘these: ‘the “hardware”: delete and: ‘the * software” delete. 


In character ‘mode orily (MODE=STD), ‘by wiring the: program connector- board, you 


can cause the hardware ‘itself to recognize one of the incoming tape codes as a 


‘character to be deleted, which it: does not transfer to main storage. It skips this 
character, without leaving a°space in its’ place, and goes on to read in the next data 


character. This is called the “‘wired’ or ‘hardware’ delete; but-such a character 


- Cannot be used: in ee mode. 


To prevent a character you want frosted as a cidatete fon Béing qead into main 
storage in binary mode, you must so designate - ‘it in’a’scan table that you specify to 
data management via:the SCAN keyword parameter ’ ‘of the DTFPT declarative macro 


that defines the file (17. 5.3:1): You: may specify more than’ one delete character this 


way — these are’ called “software” deletes,‘ because the data management software 
takes care of them — in both binary. and character modes. ‘ 


A major use of the delete character, as suggested, is to obliterate unwanted 
characters from. your paper tape file when-these- are identified in later processing, 
once the file is created. However (with one exception), you must take pains never to 
include the delete character in your output data when you are creating a paper tape 
file; it is punched into the tape by other means. Because of this use in cancelling out 
any tape code, ae delete is often called: a “‘rub-out” character. 


The exception ‘to “the general eile of always excluding the delete character from 
appearance among the data characters in your output is its use as the record gap 
character when you are punching a tape (17.3.4). 


The other uses of the delete, to constitute the paper tape leader:and trailer, or the 


interrecord gap (the record gap character) in ‘Standard mode, have already been 


referred to. In these uses, it is important to remember that the delete character must 


.be the hardware delete, to be wired for.input files via the program connector: board, 
“and not one of the software deletes designated in a’SCAN table. You may place the 


hexadecimal code for the hardware delete in your |/O area as many times as you 
want it punched in the.-header. or-trailer, or you may form these. file-delimiting 


-. character ‘strings by splicing | already" punched Strips of tape” onto’ the ends of the file 


after it is punched without them. 
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Stop Character 


Undefined records, used: only when you are. processing ..in character mode 
(MODE= STD), require some means of delimitation, as: they vary in length. For this, 


_.. you. use an-end-of-record stop character at. the low-order end of the record; it is 
. placed there automatically by data management when. you are punching an output 


file. It is read into your |1/O area from an input file, and marks the farthest point into 
your |/O area you should: attempt, to reach in. processing your data. You specify to 
data management what it is to use for this character on an output file by means of 
the EORCHAR: keyword parameter of the DTFPT. declarative macro defining the file 


(17.5.6); for an input file, you must specify the end-of-record stop to the 0920 paper 


tape subsystem itself by wiring the program connector board (17.2.1.2). When the 


-.. Subsystem encounters this character on: reading an undefined record in character 
mode, it automatically stops. tape motion. Remember that in binary mode the 


subsystem cannot be wired to recognize a stop character. The end-of-record stop 
character may not be used in OS/3 as the record gap character. 


‘ The use of an end-of-record stop character affects the length of your I/O buffers and 
, work. areas in character mode (MODE=STD); these effects are discussed in detail in 


17:5.1.3, 17.5.1.4, and 17.5.1.6. Figure 17—2 shows the relationship of record length 


.. to the block size specification for an undefined record of the maximum size in a file. 


Note the position of the stop character in some of the subsequent figures, also. 


UNDEFINED RECORD (USED IN CHARACTER (STANDARD) MODE ONLY) : 





LEGEND: 


E 


End-of-record character, a ‘‘wired’stop” character placed by data management .as a delimiter at the end of each 
undefined (variable- length) record. Specified by the. EORCHAR keyword of a DTFPT declarative macro defining an 
eureut Paper. tape file; set for inpet files with elipren wires: in the reader section of the program connector. 


it 


_ Length of data record, which may not exceed’ 4094 pes For output files, you load this ena into the. register 


specified with the RECSIZE keyword of the DTFPT macro..For input files, data management loads the RECSIZE register 
with the length of each record it reads in. - 


_ Assuming that:D is the length of the one data record in the paper tape file, then | as depicted here equals the 


BLKSIZE specification, which may not exceed 4095 bytes. The BLKSIZE specification is the size of the largest: logical 
record to be processed and always includes 1 byte for the EORCHAR stop character that follows the data in an 
aesHnee record. 


Figure 17—2. Undefined Paper Tape Record of Maximum Size for the File: 
Relationship of Record Length to BLKSIZE Specification 


17.3.2. Letter and Figure Shift Characters 


Only when you are processing in character mode (MODE=STD) may you use the 
letter/figure shifting capability that data management offers to permit you to represent 
more characters than you have unique hole patterns available in the number of data levels 
or tracks in your tape. 
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Setting aside a few of the hole patterns for the null character, one or more deletes, and (if 
you have undefined records in your file), the end-of-record stop, you can nearly double the 
number of characters that the remaining hole patterns represent if you select two more to 
be shift codes: and then assign two meanings to each of the patterns that this leaves you: 
one meaning when it follows the one > shift code on tape, one when it ION ONS the other. 


The conventions in 0s/3 data anauenion are that one of these shift codes is the /etter 
shift character, all hole patterns following it on tape being translated as “‘letters’’, and that 
the other is the figure shift character, all tape codes that follow it being translated as 
“figures”; Another convention is that, on opening an:input file, data management expects 
that the first record of the file begins with a “‘figure’’ unless the first character of the 
record is the letter shift code. Data management inserts all shift codes automatically as it 
punches your output records into paper tape. files, and it deletes them automatically, 
Maneletng the intervening data as required, as it reads input records from ape. . 


To represent the letter shift and he figure shift codes, you may select any of the codes 
that you can punch into the tape at your disposal — except for the null, deletes, and end- 
of-record stop. Figure 17—3 shows the appearance of an undefined output record, 
comprising both ‘figures’ and “‘letters’’, as it would appear in the I/O area after you had : 
formed it there for punching by data management, and as the record would look after it . 
was punched as the first record on tape. Notice that the letter:shift code has been added | 
automatically by data management as the first character of the’ punched record. : 


UNDEFINED OUTPUT RECORD, LESS THAN MAXIMUM SIZE FOR FILE, AS IT APPEARS IN I/O AREA 






BL KSI ZE specification: 





Record ane 


a Sen 


Data moved by user to vounteur area when he i is 
forming records to be punched on tape 








LEGEND: | ; 
WW “Letters”: 8-bit configurations user has designated to be translated by the content of: his LSCAN and. TRANS tables 


CJ “Figures”: 8-bit patterns user has designated to be translated by the content of his FSCAN and TRANS tables 


End-of-record stop character, placed in |/O area by data management; specified by EORCHAR keyword 





mM Residual data in |/O area, not processed 


Figure 17—3. Undefined Output Record for Standard Mode Paper File in 1/O Area 
and as Punched on Tape (Part 1 of 2) 
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AND AS IT APPEARS PUNCHED AS THE FIRST RECORD ON A PAPER TAPE FILE, f 
L 


LEGEND: 


QOan 





‘igang shift code (LSC), punched by data’ management, the OS/3 convention is that the first character in the fret 
record on. tape is either a “figure” or the letter shift code: -. = S. 


a3 





WY Tape codes to be translated « on input as representing ‘ letters”, | because they renlow: LSC and precede FSC 


*» . Soh ewe f 


Tape codes to be translated on input as representing “figures”, because they follow FSC and precede LSC 


| Figure shift code (FSC), never the first character of the first record on tape ae : 7 ; coe. 


‘End-of;record delimiter, a character. specified by the EORCHAR keyword of the DTFPT macro. On input, when this 
character is encountered, tape motion stops. The. 0920 paper tape subsystem. can be- wired to Tecognize this character 
only in standard mode. 


= Paper tape jssdake ( ties 


“Figured 7 17-3. Undefined Output F Record for Standard Mode Paper ne. in a O Area 
and as Punched on Tape (Part 2 of 2) : 





omy 


ak rsa eeEM =- 





Figure 17—4 shows the ralatisneisot: an lnidetifled input faced Ss Jength and: ‘contents to 
the |/O and work areas. (and to the specified block size); notice that’ the bytes in the’ data 
area beyond the ‘end-of-record stop character are: not zeroed or otherwise processed by 
data management; you should avoid running into them in your processing. 7 


The means for designating the shift codes, for designating which characters are “figures” 
and which “‘letters’’, and for translating these are described in full elsewhere (17.5.3, 

17.5.3.1, and 17.5.5, for example) under the DTFPT macro Rey wore parameters used for 
the purpose. See also ae 17—10, in 17.5.1.5. a 


a 
f , 
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“(for largest undefined 
record, including 
1 byte for EORCHAR). 


. .. Bytes beyond 
yp OP the EORCHAR (stop) 

ff >) Seharacter are not 
zeroed or otherwise 
- processed by data management. 


faa —— BLKSIZE specification — 
_» (as read into t/O area originally) 



















‘HOAREA1 © - 






letters 










va 


l .. ux 
/ 1/0 or WORK / 
| AREA 





{As made available to user. after GET instruction in. 1/0 area or work area,) with shift and delete characters removed and data translated 





— Record length loaded into RECSIZE 

tM ‘. register excludes © . ae hE hago : 

the EORCHAR (stop character) me 
that delimits each undefined record 
on tape and in 1/O and work areas. 


LEGEND: 







-EORCHAR (stop character)” 


-Lettershift character 


4 





4 Figure-shift character’ ~ 


Wy Bytes beyond the EORCHAR (stop) character. These are not zeroed or otherwise processed by data management and 
\\ should not be accessed by the user. a a es Beis Fea eter | 


Figure 17—4. Relationships of Record Length, Work Area Length, and [/O Area Length to BLKSIZE Specification 
and Content of RECSIZE Register for-an’ Undefined Record Input from:Paper Tape with Shifted Codes 


‘me? 
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17.3.3. Record Formats in Paper Tape Files 


_In defining OS/3 paper tape files, one of two record formats may be specified, depending 
on processing mode. When you are processing in binary mode, the only format you may 
specify is the fixed, unblocked format, but when you are processing in character mode 
~ (MODE=STD), you may specify either this or the undefined record format. You use the 
~RECFORM keyword of the DTFPT declarative macro, discussed in detail in 17.5.1.2, for 
specifying the format of records in your file. The two processing modes are described in 
fully in 17.5.2. 


The reason that the undefined format may not be specified in binary mode is that there is 
no way the paper tape subsystem, when operating in binary, can be made to recognize the 
end-of-record stop character that delimits the undefined record (17.3.1), yet this 
recognition is essential for input processing. 


The fixed, unblocked record may vary in length from 1 to 4095 bytes. If you are used to 
processing records that are considerably smaller than 4095 bytes in your applications, you 
may wonder whether it is possible to block them in OS/3. Paper tape data management 
does not offer facilities for blocking and unblocking records, and this is the reason you 
may not specify a blocked format in your DTF; however, because a record is simply what 
you tell data management it is, your file may indeed consist of blocked records. The only 
point is that your program must deal with the blocking and deblocking that is necessary, 
without the assist that data management offers in the magnetic tape ane some of the disk 
access methods. 


In character processing mode (MODE=STD), fixed, unblocked records may contain shifted 
characters and shift codes (they may not in binary mode), and when they do, moreover, 
you should note that they will seldom be all of one size when punched on paper tape. 
Figure 17—5, contained in a following paragraph (17.3.4), illustrates this point. Although 
fixed, unblocked records may not be shifted in binary mode, they may be translated. 


The undefined record is simply one that may be of any length up through 4094 bytes; its 
maximum length is one byte less than the limit for the fixed-length record because of the 
need for the end-of-record stop character just described (17.3.1). The actual length of 
individual undefined records may vary from record to record; it is marked by the delimiting 
stop character and referred to in the general register designated for record size (17.5.1.6). 
It, too, may actually contain blocked records, but there is no way to specify this fact to:data 
management, which has no facilities for blocking or deblocking. You must do this yourself. 


Figures 17—5, 17—6, and 17—7, presented in the following paragraph, show the 
appearance of records of each format on tape and in the data area. These records are 
followed by an interrecord gap. 


17.3.4. Interrecord Gaps in paper Tape Files 


Data management does not provide automatic facilities for punching a string of nondata 
characters (null or delete characters, for example) after each output record to serve as an 
interrecord gap. Yet a gap so constituted, especially if it contained a fixed number of these 
characters, might facilitate error recovery and would serve to distinguish records on tape. 
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If you want to create an interrecord gap for these reasons, you need only to place the 
number of null or delete characters that you have decided to use at the end of each record 
in the output of work area. There are a few considerations to keep in mind, however; 
these affect both your block size specification and (for undefined records only) the value 


placed in the general register used to refer to logical record length. 


With output files in both binary and standard modes, a byte for every character to be 
punched at the end of a record as part of an interrecord gap must be included in your 
calculation of block size, which you specify with the BLKSIZE keyword parameter of the 
DTFPT declarative macro (17.5.1.3). Furthermore, if your records are undefined, your block 
size must still allow one byte more for the end-of-record stop character, which data 
management inserts in the |/O buffer as a delimiter after the last record gap character 
you place there. Therefore, the overall length of data-record-plus récord-gap that you form 
must be at least one byte shy of your BLKSIZE specification. You also count the bytes for 
the record gap characters at the end of undefined records in the record length that you 
load into the general register that you must use to refer to record size (the RECSIZE 
register, 17.5.1.6). Refer to Figure 17—5. 


+ Block size specification as sutper rue 


Undefined record, of maximum size for its file 
(standard mode only). 


Undefined record, of less than maximum size for 
its file (standard mode only). 


rae Fixed, unblocked record, either processing 
mode. 


1/O area contents 





LEGEND: 


End-of-record stop character, punched by data management 


Bytes in I/O area beyond end-of-record stop, not processed by data management nor to be accessed by user 





IRG Length of interrecord gap, characters supplied by user 


Figure 17—-5. Undefined and Fixed, Unblocked Records Followed by Interrecord Gaps 
in Output Paper Tape File, Either Processing Mode 
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With input files processed ‘in character mode (MODE=S1TD), ‘nulls or deletes at the end of ‘ 
each record are: not included ‘in your -BLKSIZE* specification, because they are not 
transferred into main: ‘storage. For the same reason, data management does not include 

the bytes for the record gap characters-in the'record length it loads for undefined records 

into the RECSIZE register. A standard mode output file containing interrecord gaps would 
therefore require a smaller BLKSIZE Spoel canon when it is read in than it needed when 
pinched. Refer to Figure 17—6. | 


Block size when created 


Input Files © -: 


Undefined record, of maximum size for its file, as 
punched on tape with the interrecord gap 





Content of 1/0 area when the same undefined 
record is read in in character mode 
(MODE= STD) ee 


Block size when created 


Fixed, unblocked record as punched on tape 
with interrecord gap 





Content of 1/O area when the same fixed, 
data unblocked record is read in in Pelee mode: 
~(MODE=STD) -; Tre : 





IRG Length of interrecord gap, characters supplied by user when files were created. Punched on tape, but not transferred to main 
storage on input in character mode ({MO[ E=STD) 





Figure 17—6. Undefined and Fixed, Unblocked Records Followed by Interrecord.Gaps 
in Input Paper Tape Files, Standard Processing Mode 


(ote, 
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For input ‘files aroeseeean in bine Se aaus, on the other hand, the situation is different. 
Because the record gap . characters are transferred into main storage (as nulls, 
hexadecimal OO) at the end of each record, you: must include the fixed number of bytes ° for 
calculating block size, as well as programming appropriately to account -for their presence. 
A binary mode file containing interrecord gaps would have the same BLKSIZE specification 
for input processing as it had when punched. Refer to Figure 17—7.° 


—— Block size when created 





Input File 


Fixed, unblocked:record as punched on tape in 
binary mode with interrecord gap 





yas 







e@eeeeeee Same record in |/O area when read in in binary 
mode 


-eeneeer block size on input eee 


CESEND. 


IRG ccna of interrecord gap. Characters supplied by user when file was created. In binary mode, these characters are. 
read into main storage as input and must be included in BLKSIZE specification and in reserving main storage for 1/0. 
area. 


Figure 17—7. Fixed, Unblocked Record Followed by Interrecord Gap in Input Paper Tape File, Binary Processing Mode: : 


It might occur to you that, when you are processing output files in character mode 
(MODE=STD), you ‘could punch a string of end-of-record stop characters, instead of nulls’ 
or deletes, as an interrecord gap between undefined records. Although you cou/d punch a 
series of these characters, when your file is read in, the device would stop tape motion at 
each of the end-of-record characters, and: could not be made to skip over them. Other 
paper tape systems you ‘are familiar with may allow consecutive end-of-record characters, 

without intervening data, to be punched in output tapes and skipped over on input — 
OS/3 does not provide the facility to skip these on input. 


Figures 17—8 and 17—9 depict shifted undefined records and shifted fixed, unblocked 
records as they exist on tape and appear in your work area when processed in character 
mode (MODE=STD). 
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anaes aes 


an 
a 






“figures 2. ee letters if t - figures 





record A, i i “8% * . ‘record 2 e 3 ¥aH 


Shifted, sindstined records, each followed by a user- siipplicd interrecord gap as they appear on tape . 


Sa a specification and length of work $$ 





record 1 


The first undefined record as made available to user in work area by GET macro. 


LEGEND: 


WW Bytes in work area beyond end-of-record stop character, not to be accessed by user 


Figure shift character inserted and deleted by data management. Precedes each String of figures except those 
beginning first record or tape 


oF, 
fo 


: Letter shift character inserted and deleted by data management. Precedes each string of letters in every record on 
4 tape gn 


4 End-of-record stop character, delimiter for each. undefined record. Specified for input file by wiring program 
4 connectors board 





IRG Interrecord gap, characters supplied by user. Not transferred to main storage in character mode (MODE=STD). - 
NOTE: 


The record length placed by data management in the RECSIZE register does not include the end-of-record. stop: character — 
even though this character is read into 1/O area and is moved with the record into the work area. 


Figure 17—8. Shifted, Undefined Records as They Appear on Paper Tape and in User Work Area: 
Input File, Character Mode (MODE=STD) 





rn, 


gente, 
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figures letters 





: dp EE SS a 
ee ee ail letters e-e @@¢@e 
SS 


Record 1°, i. : gna? - . Record 2 Record 3 








| 


SE ~_ 


Dae wc mce ase 


and size of each work area smaller than output 
blocksize by the fixed’ number of record gap» * 
characters punched between records 


i 


LEGEND: 


Letter shift code, inserted and deleted by data management 


Figure shift code, inserted and deleted by data management 


{RG Interrecord gap, a fixed number of characters supplied by user on output but not transferred on input in character 


mode 
NOTES: 
1. Record 1, including its interrecord gap, is two bytes larger than specified by the BLKSIZE keyword at output because of 


the shift codes required after the first and second fields and inserted there by data management. 


2. Record 2, likewise, is one byte larger than the output BLKSIZE specification (which must include the fixed number of 
record gap characters you supply for each record), because of the letter shift code required. This record begins with a 
letter, and the preceding record ended in a figure. 


3. Record 3 is exactly the length specified by the BLKSIZE keyword at output. No shift code is required: the record 
contains only letters, and the preceding record ended with a letter. 


Figure 17—9. Shifted, Fixed, Unblocked Records on Paper Tape and in Work Areas: 
Input File, Character Mode (MODE=STD) 


17.4. PROCESSING PAPER TAPE FILES 


The procedures in processing paper tape files are simply summarized. Before creating your 
program, you obviously will know what form of tape you are going to read or punch, 
whether it is to be in binary or character mode, whether it is to be translated into or from 
the standard EBCDIC, and whether it is to contain shifted characters or rely on only one, 
unique use of the codes available to you. Once these points have been determined by the 
nature of your application, you will take the following steps to use the paper tape data 
management system: 


= You define each of your paper tape files, using the keyword parameters of the DTFPT 
declarative macro to specify your requirements. 


= Before reading or punching any data from or to any paper tape file, you issue an 
OPEN imperative macro to initialize the file. 
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= At this point in your program, you may issue the GET imperative macro to read data 


-~ from the file, or the PUT macro to punch data into the tape. Note that: you cannot 


-issue both macros-to the same file in any one pass. 


2 After all data has been ‘punched ont® a tape, or read from it, eu issue a CLOSE 
imperative macro to terminate your processing of it. 


At program execution time, you must do the following: 


= Provide proper device assignement and logical file definition for each file, through job 
control DVC and LFD statements. 


= Ensure that the program connector in the 0920 paper tape subsystem is properly set 


up. 


m Ensure that the proper paper tape is mounted and that the device is online. 


The following paragraphs describe the four imperative macros you may issue to a Paper 


tape file: OPEN, CLOSE, GET, and PUT. 


%, 
He, 
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OPEN 


17.4.1. Initializing a Paper Tape File (OPEN) 


Before issuing any of the other imperative macros to it, you must issue~an OPEN 
‘imperative ‘macro to the:paper tape file to be processed. The transients and overlays called 
as a result link your file to the device you have Beelgned through i control and Perform 
other: alle initialization proces me BS 


For an input file, 465 ata rnible: that contains letter /figure shift codes, the OPEN processing 
initializes the file so that the first record on tape is read in the figures mode. If the first 
record on a paper tape actually begins with letters, therefore, a letter shift code must be 
the first character punched on tape, or the record will be misread. This code i Is inserted 
automatically for tapes punched by OS/3.. 


Format: 










A OPERATION A OPERAND 











[symbol] } filename-1 “ee 
(1) _— 


Positional Parameter 1: _ 


filename | _ 
Is the label in your program of the DTFPT declarative macro defining the. paper 
tape file to be initialized. You may initialize as many as 16 data management 
files with. one OPEN macro call; they need not all be paper tape files. 


ta, ¥ 


1) or 1 
Indicates that you have preloaded general register 1 with the address of the 
DTFPT. declarative. macro. You use this form only when you. have a single file to 
initialize. 


Examples: 


LABEL AOPERATIONA OPERAND A 
6 


1 
|./POOL | DPEN | DMPT|,, DMPT2 


1. Opens paper tape files DMPT1 and DMPT2 


2. Opens the paper tape file DMPT7 
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CLOSE 


17.4.2. Terminating Paper Tape File Processing (CLOSE) 


When you have completed processing your paper tape file, you must issue the CLOSE 
imperative macro before taking any.action to terminate the job (such as issuing supervisor 
macros EOJ, CANCEL, DUMP, etc). Transients. called: by. the CLOSE macro ascertain 
whether all I/O operations have been completed, process errors on the final I/O 

operations, and so forth. If you require further PIpeGee ne on the paper tape file, ein must 
reopen it, with the OPEN macro. | | ; 


Format: 






A OPERATION A OPERAND 








filename-1 [,...,filename-n] 
(1) 

1 

* ALL 


[symbol] 


Positional Parameter 1: 


filename . 
Is the label in your program of the DTFPT declarative macro defining the paper 
tape file whose processing is to be terminated. You may close as many as 16 
data management files with one CLOSE macro call; they need not all be paper 
tape files. 


(1) or 1 
Indicates that you have preloaded general register 1 with. ‘the address of the 
DTFPT declarative macro. You use this form only when you have a single file to 
terminate. . 


*ALL 
Specifies that all files currently open in the job step are to be closed. 


ria % 
i 
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Examples: 


LABEL Soe OPERAND 
16 


I, P30] ELBSE] DPT »DMPT 2 
ree 
thtt 
AL 
ECan 


ex 


a~ 
i a 


' 1. » Closes the files: apeled pMEn and DMPT2 


Se: "Closes the file labeled EX1 


17-19 © 
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GET 


OTT. 4. 3. Reading a Logical Record from 1 Paper Tape (GET) | 


. You i issue the, GET imperative macro to. an input file to make a logical record available to 
you either.in a work area or in an I/O area. In executing a GET macro, before data 
management makes an input record available to:you in an I/O area or moves it from there 
‘to your- work area; it has removed all shift or delete characters from the record and has 
translated | all data that requires translation. 4 NS a noes 


If you want to use a work area for processing input records, you must specify the WORKA 
keyword parameter in the DTFPT declarative macro defining the file and must also specify 
the address of the work area with each issue of the ‘GET macro. If you do not specify the 
WORKA keyword, you must access each record in an 1/O area. And, if you have specified 
two I/O areas but no work area, you must use an 1|/O register to access the record 
(17.5.1.4). 


When your record is an undefined record (RECFORM=UNDEF), the end-of-record character 
appears in the data area at the end of the record; furthermore, any unused bytes in the 
area beyond this stop character are not zeroed or otherwise processed by data 
management (refer back to Figures 17—3 and 17—4, for example). If you wish, you may 
specify a record size register when you are reading undefined records. Data management 
then loads this register with the length of the record, as it appears in the data area minus 
shift and delete characters; this length does not include the end-of-record stop character. 


Format: 
LABEL A OPERATION A OPERAND 


filename , (workarea 
(1) (0) 
1 0 ; 


[symbol] 





Positional Parameter 1: 


filename 
Is the label in your program of the DTFPT declarative macro defining the input 
paper tape file from which you are reading a record. 


(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFPT file 
table. 


Positional Parameter 2: 
workarea 


Is the symbolic address (label) of your work area. You may change this label from 
one GET macro to another. 
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(O) or O 
Indicates that you have preloaded register O with the address of a work area. 
Examples: 
1, LABEL et fa _ OPERAND | A 
i PAL 
(2h...,1,, | GET, | MPT 2, Wk L, 
3 doos Tea He 0, WKS 
Pe HGET, | DMP TS, 00), 
| 1. Read a ‘record from paper tape file labeled DMPT1 and leave the record in an 1/0 
area. er | . . | Las er 
2, Read a a record from paper Tepe file labeled DMPT2 and move the record to the 
work area. labeled WK1. = hose = eta 


Read a record from. paper tape file labeled DMPT3 and.move the record to the 
work area labeled WKS. a at . 
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PUT 


17.4.4. Punching a Logical Record. into Paper Tape (PUT) 


Having provided.the data for an output.record in. an I/O area or work area, you issue the 
PUT imperative macro to punch it as a logical record into paper tape. If you are using a 
work area, you must specify the WORKA keyword in the DTFPT declarative macro that 
defines your output file, and you must specify the address of a work area with each PUT 
macro you issue. The work area may differ from macro to macro. 


Data management moves the output record from the: work area to the output area and, 
before punching the record on tape, inserts letter’ and figure shift characters and 
translates data as necessary. If this is the first record on the tape, and if it begins with a 
letter, data management automatically punches the ‘letter shift character as the first 
character of the record. If the record format is undefined, data management punches the 
end-of-record stop character at the end of each record. You will have specified the shift 
‘characters with the LSCAN and FSCAN keywords, andthe end-of-record character with 
the EORCHAR keyword, when you defined the file with the DTFPF declarative macro. 


To punch out undefined records, ‘you must also have specified a record size register, ‘using 
the RECSIZE keyword in the DTF, and, determining the length of each record, you must 
load this length into the register before you issue each PUT macro. The number you load 
into the RECSIZE register is the number of bytes of data in the record; it does not include 
bytes for the end-of-record stop character nor for the shift characters, which data 
management inserts. 


Format: 








A OPERATION A OPERAND 


filename) | , (workarea 
raven este 
1 0 





LABEL 















Positional Parameter 1: 
filename 
Is the label in your program of the DTFPT declarative macro that defines the 
output paper tape file. 
(1) or 1 
Indicates that you have preloaded register 1 with the address of the DTFPT file 
table. 


Positional Parameter 2: 


workarea 


Is the label in your program of the work area from which you want the output. 


record moved. 
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(0) or O 7 
Indicates that you have preloaded register O with the address of the work area 
from which you want the record moved. 


Examples: 

d LABEL AOPERATIONA. OPERAND- A 
EX500, | (PUT EX 

See PUT | [DMPTS,, WKA, 

eeevna OREN 
Poe HEA TO WKA 
Pit. LUT, [DMPTS), (0) 


1. | Punch a record which the user has placed in an |/Q. area, into the paper rape file 
_ whose label is EX7.: . ; 
2 Move the record that the user has placed in the work area labeled WKA to. an. 


1/0 area and punch it into the paper. tape file whose label is DMPTS. | 


ad 


Same as 2. 
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DTFPT 


17.5. DEFINING PAPER TAPE FILES (DTFPT) 


You define your paper tape files to data management by issuing a DTFPT declarative 
macro for each file you will process in your BAL.program, using its keyword parameters to 
describe the file. The DTFPT macro does not generate executable code (and therefore 
should not be issued in the midst of executable instructions or imperative macros); it does 
generate a file table to contain data about the file and the results of processing. 


When your program is assembled, the assembler expands your DTFPT declarative macro 
into a 215-byte file table, which it uses ina number of ‘ways to control file processing and 
to record certain results. 


As you execute each imperative macro to process your file, for example, data management 
places an informative reply, indicating normal completion of !/O or exceptional conditions 
(including unrecoverable error) ina program- -addressable field of the DTF file table called 
tilenameC. Your use of this field is explained under the ERROR keyword parameter 
(17.5.9), as is” the use of another field, filenameD, to access a record containing a parity 
error. 


Following is a format delination of the DTFPT declarative macro, showing the required and 

optional keyword parameters you will use to define your file and to indicate to data 
management some of your file processing requirements. Notice that the keywords are 
listed here in alphabetic order; however, you may issue them in any convenient order, 
separating them with commas. 
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“Format: i  8hU Ati aan, CAPER 


A cia a al Aart 


LABEL A OPERATION A 0S ORERANOD. Oe oo mee 


-<) filename |- “DTFPT.. .~. |. BLKSIZE=n sofa 
Sia S adt Tate eae owes os to, L EOFADDR= eimbelle 
oe ee el = [ BORCHAR=expression] . ©. . 
poten moore. -L;ERROR=Ssymbol]: . are 
po ess) ST FSCAN=symbol]” ee 
[, FTRANS=symbol] © ~ 
,OAREA1=symbol 
[ LOAREA2=symbol] 
[ lIOREG=(r)] 
[,LSCAN=symbol]< - 
[,LTRANS=symbol] 





FOVBLKSZ=n oo 
LOPTION=YES] °°, gates 


|RECFORM=| i a 
UNDEF 


[, RECSIZE=(r)] ; 
L.SAVAR EA=symbol] 
[.SCAN=symbol] _ 
[, TRANS=symbol] — 
TYPEFLE=3" 7 ] 
OUTPUT 

[ WORKA=YES]. .- . 








A comma is shown preceding every keyword but the first, to remind you that all keywords 
coded in a string must be separated by commas. However, a comma must not be coded in 
column 16 of a continuation line, nor follow the last of the string. Refer to the preface of 
this manual for OS/3 format statement conventions and to 1. 6. .3 for rules on continuation. 


The symbolic label of the DTFPT declarative macro (filename), required for all DTEPT files, 
is the logical name by’ which you address’the file in your BAL program; it may contain no 
more than seven’ alphanumeric“ characters, the first. of: which. must be... alphabetic. 


Restricting filename to seven;characters allows.data management to generate ‘symbols, 
such as: filenameC, which you ‘may reference. in each DTF file table by concatenating. a 


letter to the file name. You specify this file name to the imperative macroinstructions!you 
issue to process your file, and it is this name also that you use in the job control /ogical 
file definition (LFD) statement with which you allocate the file. 


UP-8068 Rev. 4 SPERRY UNIVAC OS/3 17-26 


BASIC DATA MANAGEMENT... 


Notice that there are two keyword parameters (BLKSIZE and IOAREA1) that you must 
always specify in every DTFPT macro. Others are es mneer certain circumstances, 
and some are e entirely up. to you. ; 

Notice also that the completion of many of the keyword parameters is symbol, 
representing the fact that with symbo/ you specify the symbolic address of the subroutine, 
translation table, scan table, or 1/O buffer the keyword stands for. In expanding your 
DTFPT declarative macro, the assembler generates an EXTRN pseudo-op for each symbolic 
label the macro contains; this means that the corresponding subroutine or table ‘need not 
be assembled with the DTFPT macro, but, when it is more convenient or advantageous for 
you to do so, may be assembled separately. 


These are the keywords in point: 


Keyword Sipsdttion ahs 
EOFADDR 17.5.4 | 
ERROR 17.5.9 
FSCAN 17.8.5 
FTRANS 1753 
IOAREA1 17.5.1.4— 
IOAREA2 17.5.1.4 
LSCAN 4753 
LTRANS 17.5.3 

- SAVAREA ‘17.5.8 | 

7 SCAN ——=«i17253 

TRANS | 1753.1 


Table 17-1, following: ano DTFPT format delineation, summarizes the rules for sepaciving 
the keywords. The. keywords. are discussed, in full detail, in the subsequent paragraphs. 
Information on acceptable variations of some of the keywords is given in 17.6, which 
discusses the compatibility of . OS43 with certain other oo management systems for 
npepet seve: , | 
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Table 17—1. Summary of DTFPT Keyword Parameters (Part 1 of 2) 


Use With 
File Type EXTRN 


tt 




















Use 
Without 
Shifted 





Required for all files, Specifies maximum fength, 
in bytes, of largest logical record; a is a decima! 
number in the range 1 through 4095 









Specifies label of user's end-of-tape processing 
routine; required for all input feles, 


— 






hee [eee 






Required for output files with undefined records; 
specifies end-of-record stop character (delimiter) 


RECFORM= 
FIXUNB, 















MODE=BINARY 

























ERROR symbol Specifies label of user's error routine. If not Yes 
specified, errors return intine 

FSCAN symbol Required, with LSCAN keyword, to specify label Yes 

: : of user's figure scan table for punching files with - 

shifted codes i 

FTRANS symbol Required, with LTRANS and SCAN, to specify Yes 
label of user's figure translation table for 
Processing a shifted input file 

fOAREA1 symbol Required far all files; specifies label of primary Yes 
1/0 buffer 

tOAREA2 symbol Specifies label of optional secondary 1/O buffer. Yes 
Requires specification of IOREG if work area 
processing is not specified (WORKA keyword} 






Specifies, in mandatory parentheses, the number 
~ of the general register to be used as [/O. index 

register. Required when IOAREA2 keyword is 

specified, but work area processing is not. 
{WORKA keyword!’ | * 








_ Required, with FSCAN keyword, to specify - * MODE=BINARY 


. J 
fabel of user's fetter scan table to punch files 


LSCAN symbol 
. with shifted codes : . 
LTRANS Required, with FTRANS and SCAN keywords, . 
: to specify the label of the user’s letter transta- 
nd tien table for an input file with shifted codes 
a BINARY Required to specify binary processing mode 


sTo Specifies character {(nonbinary} processing 
mode 
OPTION Specifies optional file processing 


OVBLKSZ Specifies use and fength of oversized 1/O 
buffers for processing fixed, unbfocked 
records containing shifted codes; a is a 
_ decimal number ranging from 2 through 
4095 and must be st Jeast one byte larger 
_ than the BLKSIZE specification. 


RECFORM* EI JNB: : Specifies fixed, unblocked record format 
record stop). Output files require 


UNDEF 
Z RECSIZE register. : E 
RECSIZE Specifies, in mandatory parentheses, the 
. . . humber of the general register to be used 
to refer to length of undefined records. 
Required for output files; optional for 
input.” 


7 | 
symbol 
Optional, with TRANS keyword, for 
: . character deletion in either mode 


TRANS. symbol Specifies iabel of user's translation table, 
* for any file but a shifted input file 


OUTPUT Required to specify an output file— Yes r Yes’ i 
punch only i 


YES Specifies double buffering via work areas, ae a Yes 4 
which user must specify with each GET 
or PUT macro, ignored if (OREG keyword 
is specified 

























_ TRANS, ’ 
MODE=BINARY 












RECFORM=UNDEF 13.5.2, 
: 13.6.2.1 
Yes Yes 13.5.2, 
13,5.2.2 
es areas eae | 


RECFORM=UNDEF, 


tte, 
















. | MODE=BINARY | 









Specifies undefined record format {varying 


_MODE=BINARY 
length). Records require delimiter (end-of- 2 








RECFORM=: 
FIXUNB,-. 






















(MODE=BINARY | 


ina 


Q 





Specifies label of 72-byte storage area, 
fullword-aligned, in which data manage- 
ment saves contents of user’s general 
registers during execution of imperative 
macros, If not specified, data management 
expects save area address in register 13. 








rb 7 C 






Specifies label of user's input file shift 
code scan table, Required for input files 
with shifted codes (MODE=STD); 
FTRANS and LTRANS keywords must 
also be specified. Optional for software 
character deletion in binary mode. 














FTRANS, 






LTRANS. 


feo - pai 
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Table 17—1, Summary of .DTFPT Keyword Parameters (Part 2 of 2) f 
LEGEND: 
oR Required to be specified, beat or we default 


O “gpedineation te is pare 





Default value assumed ” data management if keyword is not specified 





— __ Not pertinent 
_ NOTE: 


A “yes” entry in the column headed ‘ ‘EXTRN” indicates that the assembler generates an EXTRN pseudo- op for the symbolic label 
specified. This means that your coding that defines the subroutine, table, or main storage area’in point may be assembled 
separately Horn your DTFPT macro. You will need an ENTRY for each EXTRN. 


1761. Basic ‘DTFPT Keyword Parameters 


The following subparagraphs explain several basic keyword parameters that you use to | 
indicate to data management how to set up the file table according to certain of the | 
fundamentals of your processing. With these keywords, you-establish whether your file is 
an input or an output file, what the record format is, what the record and block sizes are, 
whether you are using oversized butlsie, and which, if either, of the double- buffering 
options you are using. . 


17. 6. 4. i: _ Specifying File Type. (TYPEFLE) 6.73 _ _— : | -_ Se 


Bata fasriegement provides two types of paper tape file: input ‘and output; He combined 

file is not supported. The input file allows the use of the GET imperative macro to read 

data from a paper tape (17.4.3) and requires you. to code a routine for end-of-tape | 
processing (17.5.4). An output file allows the use of the PUT macro to punch data on a 

paper tape (17.4.4). If your 0920 paper tape subsystem is configured with both a punch 

and a reader, simultaneous reading and punching are possible, but on different pieces of | 
tape; each of these requires separate definition with a DTFPT declarative macro and 

allocation with its own DVC — LFD job control device assignment set. You should use a 
different file name for each DTF. : 


Keyword Parameter TYPEFLE: 





Indicates that this DTFPT macro. defines. an input paper jace file, one that you 
want to read. You must specify the label of an end-of- -tape processing routine for 
every input file, EOFADDR keyword Parameter (17.5.4). 


- TYPEFLE= OUTPUT 
~ . Must be specified to define an output paper tape file, one that you want 
punched. 


If you omit the TYPEFLE keyword, data management generates an input file table by | a 
default; EOFADDR keyword must still be specified. ‘ 
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17. 5. 1.2. Specifying Record eon eae 


In the 0S/3 paper tape. aaa. imanagement eysieni. you have but : two — formats 
undefined (that is, records of various lengths) and fixed-length, unblocked. In the standard 


(character) processing mode, you may use either format, but only fixed, unblocked records 
may be gigesciia in oe 


The reason rae this is ‘that, in the eiinanve procéssing: mode, the 0920. paper tape subsystem 
cannot be made to recognize the:end-of-record stop character used as a‘delimiter to mark 
the ends of undefined records, which vary in length from record to record. Input paper 
tape processing of records with varying lengths depends on the recognition of the 
delimiter to stop nape: motion. Bee eucaus ‘when a qeeele nas been eee: 


For processing eutat fies with undefined: records: you must ane both an. end- of- Seid 
stop character: with the EORCHAR keyword:(17:5.6), and a general register to be used for 


referring to. record size (the RECSIZE register, 17.5.1.6). Before you issue the PUT 
.imperative macro to punch an. undefined record, you determine its:length and place this 
number in. the two least: significant bytes of the: RECSIZE register. The length is measured 


in bytes and does not include the byte for the EORCHAR stop character. The number must 
be positive and in the range 1 through 4094. When you issue the PUT macro, data 
management places the stop character at: the. end of each enced record in the 10 
area perone puneeing ue whole contents’ into the tape: a 


When you are processing an anit “file containing undefined: records: your. use of the 
RECSIZE register is optional; if you specify it, data management loads it with the length of 
each record read in; again, this length does not include the EORCHAR stop:character. You 
must wire the program connector of the 0920 paper tape subsystem to ions the. ead 
of-record stop character that is punched in the tape (17.2.1.2). a e ohe 


poe Paremenes haealids 





Specifies that the. record orn is 5 fixed and unblocked: Only this fornia’ may be 
used in binary mode. You specify record length with the BLKSIZE keyword. 


RECFORM=UNDEF 
Specifies that record length varies from record to record and that records are 
_ delimited by:.a wired stop character (EORCHAR keyword).’Length of each record 
is defined via the RECSIZE register. This record format ‘is not valid for binary 
mode; if so specified, a diagnostic appears inthe DTFPT macro expansion in your 
Booey listing, and RECFORM= i is miaeaee 





If the RECFORM eayward is ominted: data. Pacnageniencea assumes that: the reer 
format is fixed, unblocked. 


17.5.1.3. Specifying Block Size (BLKSIZE) = 


The. maximum number of bytes that data management: can transfer between paper tape 
and. main’:storage in. one access.is:' 4095: bytes. (If you are familiar with OS/4 data 


management, you i secegize this augue’ as thes maximum toe size in ret pihaLD as 


well.) . 
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The maximum block size limits the length of:your logical records. For the undefined record 
(RECFORM=UNDEF, 17.5.1.2), because the EORCHAR stop character must be included in 
the specified block size, the longest logical record is 4094 bytes. When you are processing 
undefined records,: your |/O buffers and work areas must be at least. as. tong as the 
number of bytes specified as the block size. : , 


When you are processing fixed, unblocked records, which do not end in a stop character, 
your block. size specification is the maximum length of a logical record and, because it is 
the number of bytes moved to-.or froma wee area, each work area must be at least as 
long as the sspecltica block size. 


For neither ecu format ieee the specified block size need to account for the presence of 
shift characters, which data management inserts and deletes. When you are processing 
fixed, unblocked:records, however, with shifted codes, you may specify that your |/O areas 
are larger than specified block*size, using the. OVBLKSZ keyword (17.5.1.5). When you do 
this, you must also reserve at least as many bytes of storage for each I/O area as you 
specified with the OVBLKSZ keyword, but. you need not reserve more for each work area 


than you specified with the BLKSIZE keyword. Do not specify the OVBLKSZ keyword 


unless your fixed, unblocked records contain: er ittag characters. 


With SutpuE tapes: additional bytes fot any a ehiaacete to be punched at.the end of a fecord 
to serve as an interrecord gap (17.3.4) must be included in your BLKSIZE specification. 
With character mode input files (MODE=STD), however, nulls or delete characters at the 
-end of each record are not. transferred into main storage and must not be included in the 
-BLKSIZE specification. The situation with binary mode input files is the same as for output 
files: because: record gap characters are transferred into main storage (nulls as 
hexadecimal OO), you must-include them in caruiaiing block size, as well as programming 
as necessary to deal with them. ; 


When you issue the OPEN imperative macro for a paper tape file, the OPEN transients 
check your BLKSIZE specification for validity. If there is no specification, or if the number 
of bytes specified is other than 1 to 4095 bytes, the file is not marked open, and you may 
not process it. Refer to 17.5.9 for the resulting data management error processing. 


Keyword Parameter BLKSIZE: 


~BLKSIZE=n 
Required for all iagat ‘and eutbut paper ‘ape files. Specifies the length of the 
largest logical record to be processed; where n, a decimal number ranging from 1 
through 4095, is the measure of this length in bytes. 


If omitted, an error message appears in the DTFPT expansion in your assembly listing; 
_ the-file cannot be opened for processing. 7 | 


17.5.1.4. Specifying Buffers, Work Areas, and Double- cneolnee (IOAREA1, 
IOAREA2, IOREG, WORKA) | 


You must always specify at least one I/O buffer for each paper tape file, using the 
IOAREA1 keyword parameter of the DTFPT declarative macro. When you'specify only one, 
however, and do not use.a work area, you have.no means of overlapping I/O operations 
with your processing: each |/O operation must be completed before data management can 
return control to your program. (The reason for this is to prevent your inadvertently 
changing the data in your buffer before the I/O operation is completed.) 
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To increase your throughput over what this situation affords,.data management offers two 
methods of double-buffering: specifying a secondary |/O buffer and an index register to 
point to the current one (with the IOAREA2 and IOREG keywords), or using one or more 
work areas for processing while your I/O takes place from or to the IOAREA1 buffer. With 
either of these mutually exclusive alternatives, you. benefit..Double-buffering allows data 
management to initiate an |/O operation.and to return to you before it is completed. While 
the |/O proceeds in-one area (don’t change the data in this one!), you may process in 
another. This overlapping of |1/O and processing epouey epeers up the execution of your 
program. iba a 


No additional throughput is gained, however, if.you:specify a secondary I/O buffer and use 
work areas at the same time. Although OS/3 allows this. eombinallgn of. areas, it does not 
allow both double-buffering methods at once. - oo 


If you are going to use work area double-buffering, you must. inform data management of 
this by specifying the WORKA keyword in the DTFPT macro (the specification is 
WORKA=YES), and you must then specify the address of a work area in the second 
operand of each PUT or GET macro you issue (17.4.3, 17.4.4). You may use. a different 
work area each time. For an output file, data management moves your data from the work 
area to the I/O area before initiating an |/O operation to the punch. For input files, data 
management moves the data from:the |/O area to the work area before making it available 
to you. Each work area you use (and there is no limit set by data management on their 
number) must be of a length of least equal to the number of bytes you specified with the 
BLKSIZE keyword (17.5.1.3). The reason for this is that data management ames moves to 
or from a work area exactly this number of bytes. ign bog, * 


If, on the other hand, you choose the IOAREA1/IOAREA2 form of double-buffering, and 
therefore do not want data management to move records to and from your work areas, you 
must establish an |/O- register to keep track of the current buffer, using the IOREG 
keyword parameter. For an output file, data management's OPEN processing’'sets up the 
specified IOREG register to point to the address of one of the I/O areas; .it changes this 
address to that of the other buffer after each. output operation. Before you. issue a PUT 
macro, therefore, you must move the data you want punched to the.current I/O buffer, 
using the IOREG register to access the record.:For input processing, after each GET macro 
you issue, the IOREG register points to: the !/O buffer that contains the requested data 
just read from paper tape. You must use the IOREG register to access it... © 


When your DTFPT declarative macro is expanded, the assembler generates EXTRN pseudo-- 
ops for the. symbols you have equated to the IOAREA1 and lIOAREA2 keyword parameters; 
therefore the coding that defines these storage areas may be assembled separately from 
the coding contain the . macro. lOAREAZ, if speeition must be . the same size as 
IOAREA1. ae oye, oe, 


The length of the I/O buffers, defined by DS or DC statements somewhere in your BAL 
program, should be at least the number of bytes you have specified with the BLKSIZE 
keyword of this DTFPT. declarative macro (17.5.1.3). It must be-great enough to contain the 
longest of your undefined records, including the end-of-record :stop character (EORCHAR 
keyword, 17.5.6), but not including shift characters. Buffer length should also be no less 
than the BLKSIZE specification for fixed, unblocked records without shifted codes. When, 
however, your fixed, unblocked records do contain shifted codes, you may specify that your 
|/O buffers are /arger than your block size specification, via the OVBLKSZ keyword 
(17.5.1.5); when you do this, the storage areas you define for IOAREA1 and IOAREA2 
must not be less than your OVBLKSZ specification indicates. 
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Parameter One EAI: 


lone EAI 4=aynibale 


Required for all paper Ape? files, to: Papeciky the: eben address of the main 


“storage area reserved for use. as the primary |/O buffer for the paper tape file 


defined by this’: DTFPT declarative macro. The length of the buffer is defined 


“elsewhere with a DS or DC statement.: It must. not be less. than the OVBLKSZ 


specification; if the OVBLKSZ keyword is not.specified, buffer length must not be 
less than the BLKSIZE specification. 


_ If omitted, data management will not open the file defined by this DTFPT declarative 


resu 


ee eae 


macro, and‘an error message appears in your saan oe Refer to 17.5.9 for the 


Iting data management error processing. | 


Parameter. ORR EAS eee, 8 ae Te . mee 


_1OAREA2=symbol P Gee = : 

-: Specifies the symbolic agrees. of a Seonsan 0 ‘buffer: Scioual fob all paper 
~ tape files. Length of IOAREA2 buffer must be the same as IOAREA1, and is 
~ gubject to the: same: considerations. When the IOAREA2 keyword is: specified, 
“. unless you:specify work area processing via the WORKA keyword, you must also 

specify a gene) poaierel to rererenice the. current I/O BUNGE, ee the bist 
~ me Ore z ie ; 


Keywo a 


Baraaieter IOR EG: 


_1OREG= (r) 2 . 
’ > Specifies the etoralie register that is to be used to feferente the current 1/0 area 


when: both. the: lIOAREA1 and IOAREA2. keywords are specified for double- 
buffering, and work. area processing is not specified with the WORKA keyword. 


_ The completion, r, must be enclosed ‘in parentheses; it represents the number of 


the general register used. Registers 2-through 12 are always available for. use; if 
you specify the SAVAREA keyword (17.5.8), register 13 is also available. If you 


: - specify the IOREG keyword, you should-not also specify the WORKA keyword; if: 
. you specify both, an ‘error el appeals ‘in the ae expansion, -and the WORKA 


a as rd 


keyword is ignored. . 


Parameter ibe c pi 


WORKA=YES 


Specifies that data. flanagement- is to tere double- buffering via the IOAREA‘1- 
buffer and a user-specified work area. Data management moves an input record 
from the I/O area to the work area you specify as the second operand of the GET 
macro. It moves an output. record from the work area you specify with the PUT 


~ macro to the IOAREA1 buffer. The length of each work area is defined with a DS 


or DC statement elsewhere in your BAL program; each must have a length at 
least equal to the number of bytes specified by your BLKSIZE keyword. 
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If you specify the WORKA keyword, you must not also specify the IOREG 
keyword. If you specify both, an error flag appears in the DTFPT expansion in 
your assembly listing, and the WORKA keyword is ignored. The work area 
processing described cannot take place in this event, nor when the WORKA 
keyword is omitted. og 


17.5.1.5. Specifying Oversized Buffers (OVBLKSZ) 


To obtain more efficient processing of input or output files containing fixed, unblocked 
records that are letter/figure shifted, you may define I/O: buffers in your program that are 
larger than your BLKSIZE specification. Recall that your specified block size equals the 
length of your logical record when you have specified RECFORM= B, but that-this’ 
length does not allow for the insertion of the shift codes by data management (17.5.1.3). 
When you are using oversized buffers, you must notify data. management.that you are 
doing so by specifying the OVBLKSZ keyword, which. indicates at:the same time how long 
your oversized buffers are. | 





What this does for you in processing input files is:to allow. data. management to read in 
more characters than your fixed record length calls for. Data management removes shift 
codes and delete characters from this larger block until the “‘compressed’’ record. thus 


formed in the buffer does equal your. specification. (It.has also translated the characters 
between the shift codes with the specified FTRANS and LTRANS translation tables.) If data 
management cannot create a record equal in length to your BLKSIZE specification from 
the data in the buffer, it reads in more. When it has thus created a record of this size, data 
management either leaves this record in the 1/O buffer and returns to you, or it moves the 
record to your work area before returning to you. If you have defined |/O buffers large 
enough, this mode of processing reduces the overall number of 1/O operations required to 
process your file. Figure 17—10 depicts the:relationship of the various specifications. — 


OVBLKSZ specification 







= 
\ 





[ Saspeeeer tierra er eae ye specification — 


: 2 ee 7 seh : 4 . 3 Lot 


Figure 17-10. Relationships of Logical:Record Length, Work Area Length, and 1/O Buffer: Length to Sa 
the BLKSIZE and OVBLKSZ Specifications for a Fixed, Unblocked Record.Input 
from Paper Tape with Shifted Codes (Part 1 of 2) 
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LEGEND: 


, Figure shift character 


Letter shift character 





Bytes in 1/O area not to be provessed a user 
NOTES: 


1 The ° upper diagram depicts the record as ‘Srigirially read into the oversized 1/O buffer; it contains untranslated tape 
~ < codes and letter/figure shift codes. The hardware delete character ‘has: ‘not been: transferred to main storage, and data 
_ management has removed all software deletes before translation. 


2. The center diagram shows the record as data management makes it available to you, left-justified, in the 1/O buffer; 
the letter and figure shift codes have been removed and intervening data translated into EBCDIC. Notice the bytes in 
the oversized buffer extending Perens your BLKSIZE specification: these are extraneous to your logical record, and you 

_ Should not-access them. poe: : 


3. The lower diagtarr shows the fected: fhoved 4 into your work area, ‘the length of which snieuld be no less than your 
‘BLKSIZE Speetiction, The ‘record is pe ecg in the work: area, also. 


Figure | 17—10. Halstionshios of jeaina Record nah ‘Work Area Length, and 1/O Buffer Length to 
; _the BLKSIZE and OVBLKSZ.- Specifications for.a Fixed, Unblocked Record Input 
ed Paper Tape with Shifted Codes (Part 2 of 2) 


For. output files, the sanders takes place. Specifying the OVBLKSZ keyword allows data: 


management more room to.insert the required shift.codes into the fixed-length record you 
have supplied. It continues doing so until the oversized buffer is filled, when it writes out 
the buffer contents to be punched on tape. If necessary, data management issues 
additional I/O orders until the complete logical record you provided has been punched. 


Your OVBLKSZ specification must not exceed’ 4095 bytes and must always be at least one 
byte more than your BLKSIZE specification. When you use the OVBLKSZ keyword, you 
must still reserve storage for your |/O buffers in your program; data management cannot 
issue the necessary define storage (DS) or define constant (DC) instructions for you. 
(Recall that you may assemble this part of. your coding separately from your DTFPT 
declarative macro if you want to). The |/O buffers must be defined to include as many 
bytes as you have specified with the OVBLKSZ keyword; however, if you have specified 
work area processing, you need not reserve storage for any work area that exceeds your 
BLKSIZE specification; this is because the number of bytes that data management moves 
to or from your work areas is always equal to the block size. 


How do you calculate the extra space you need? If you know your data well, and your 
logical records follow a definite pattern, there is no great difficulty in establishing the 
number of additional characters to allow for the shift codes your records require. 
Statistical sampling of your records, nen you: do not cunow: their composition well, may 
help you estimate the space you need. 


PR, 
a 
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The worst case, of course, occurs when there is an exact alternation: every letter being: 
followed by.a figure, every figure by a letter. This situation doubles the length of your 
logical record. The best case occurs when only one shift code is required per record. Do 
not discount the possibility of timing several test runs, with an adequate sampling of data, 
using successively larger OVBLKSZ specifications until you are reasonably certain that you 
have the best trade-off of main storage space for increased processing speed in your 
application. Nor should you forget that your use of delete codes must also be taken into 
account. 


If you specify the OVBLKSZ keyword, but do not specify the WORKA keyword, do not 
access data in the |/O buffers at a displacement greater than your BLKSIZE specification. 
A glance back at Figure 17—10 shows the possibility of accessing extraneous data if you 
do. 


If you do not specify the OVBLKSZ keyword with fixed, unblocked records that contain shift 
codes, your records are processed in the |/O buffers within areas that are limited in their 
length to the BLKSIZE spectiicalign: Reserving larger buffer Space | is: then MaTiOUt useful 
effect. . 


Keyword Parameter OVBLKSZ: 


OVBLKSZ=n se 
- Specifies processing input or output records ‘in oversized I/O buffers, when 
buffers greater than your BLKSIZE specification are defined to increase 
processing efficiency of fixed, unblocked records containing shifted:data. Here, n 
is the decimal number of bytes used for buffer length; m must be at least one 
byte greater than your BLKSIZE specification, but may not exceed 4095 bytes. 


When you specify the OVBLKSZ keyword, you must define |/O buffers that have — 
a length at least equal to n; buffer length greater than 7 is unused. Work areas, 
if eperiliee: need be no enger than your BLKSIZE specification. 


The OVBLKSZ hover may not be used if RECFORM= -FIXUNB is not specified, 
explicitly or by default, or if records do not contain shifted data. ~ 


If omitted, records are processed in ane I/O puters within areas urated in length to — 
your BLKSIZE specification. ; 


17.5.1.6. Specifying Register for Record Size (RECSIZE) 


When you are processing an output file Containing undefined records, you must specify a 
general register in which you will place the length of each record before you issue the | 
PUT imperative macro. The use of a record size register is optional for input processing of ° 
undefined records; if you specify such a register, data management places in it the length — 
of the logical record that is available to you in the I/O buffer or in yeur work area before 
returning to ee from its execution of wour GET macro. _ 
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The record -size placed by: you: or data management in this register is a fixed-point binary - 
number, measuring the length of.the record in bytes; it may range from.1 to 4094 bytes. 
This length does not include extra bytes forthe end-of-record:stop character (17.5:6) nor: 
the -shift .codes,.if any, that data management inserts: However, for output undefined 
records, you must include extra bytes for any characters you’ want punched at the end of 
the record to serve. as..an interrecord gap (17.3.4).. Data ‘management. does ‘not: include . 


record gap characters in the input record length it loads into the register. 


The record size register is specified with the RECSIZE keyword and is used only in 
character mode (MODE=STD) for undefined. Records. Files Bipseseed: in eey mode i, 


not contain undefined records. . 
Keyword: Patainater RECSIZE: 


RECSIZE=(r) - 
es Specifies the. number of the general register that isto be: used 1 to refer to the. size 


of undefined records, where r is the register. number and. must be coded’ in: 
parentheses. General registers 2 through 12 are available for this use, as is © 


register 13 when you have also specified the SAVAREA Revere: 


The RECSIZE keyword is specified only when processing is in siaenciek ede 

(MODE=STD) and records are undefined (RECFORM=UNDEF). It is required for 

. output processing; before issuing each PUT macro, you must place the length of 

_. the. undefined record in. the RECSIZE register. Use is optional for input 

-. processing; data management loads the bce evedietey perore? returning to you 
Auerg each GET macro. . . 


17. §.2.. ‘Specitying File Processing Mode ciel! 

The 0920 paper tape subsystem: itself operates in Sitar i two naedes’. binary or 
nonbinary. The nonbinary mode of the hardware (for which the term character mode, used 
in this. manual, is ‘probably. more descriptive)-is the standard mode of epeiaund the 
hardware in OS/3 data management. : rer 
17.5.2.1. Highlights of Binary Mode Processing (MODE=BINARY).. 


The binary mode is designed for use only with 1-inch, 8-level paper tape. In this mode, 


each of the eight bits of a byte in main storage that represents a character corresponds to ~ 


a hole position on the tape. This correspondence is fixed within the hardware, and you 
cannot use the program connector board to change it — as you can for character mode. 


In binary mode, because you cannot wire the board so ‘iat the subevelonne can recognize | 


the stop character that delimits undefined records (thus permitting an automatic stop of 


tape motion when the hardware has read in a full record), you are limited to fixed, - 


unblocked record format. Another way in which. the binary mode differs from character 
mode is that figure and letter shifting is possible only for character mode; you have no 
need of the keyword parameters used to specify shift codes in character mode, nor 
concern for the effects of these extraneous characters on the sizes of your buffers and 
work areas. 


fo 
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Just as the subsystem cannot recognize the stop character: in binary mode, so also it 
cannot recognize a delete (or ‘‘rub-out’’) character. Data management, however, provides 
you the means for specifying what characters you want to use as deletes; this is the SCAN 
keyword parameter of the DTFPT declarative macro. When you have used this to. specify 
one or more delete characters for an input file, each record is scanned as it is read in, and 
any such characters are deleted. As the characters are removed, the record is 
‘“‘compressed”’,.and data management reads more characters from tape, if necessary, until 
the record of the fixed length you have specified is in ven buffer. (For further Geral see 
the SCAN keyword (17.5.3).) ; 


Although you cannot use shifted codes in binary mode, you may indeed specify that your 
data is to be translated. Data management translates your input or output data according 
to the table you provide in your program (or assemble separately), ePecrns its syunee 
address via the TRANS keyboard parameter ae 2 3. 2). Pi 


As to “null characters in binary mode, once your input file has been read past the tape 
leader (which must contain only null characters: 17:2.2), any null characters encountered 
after the first non-null are transferred to main storage. If, for example, you are using nulls 
to denote an interrecord gap (17.3.4), these will appear in your |/O area or work area at 
the end of each record (recall that you must include them in calculating your BLKSIZE 
specification); your program must provide for any action that may be necessary... Similarly, 
because the null characters you must use for your paper tape trailer in binary mode 
(17:2.3) are also transferred to main storage, you must do what is. Hee ESSN in your 
program to deal: with them. : 


Finally, binary mode differs from character mode in that parity checking is not possible.You 
can neither punch:a parity channel on tape nor check parity: on an input tape with the 
hardware. On the contrary, the program connector board on the 0920 paper Hpe 
subsystem is completely bypassed wien you are processing in ony mode. 


eligi Parameter oe 


MODE= BINARY _ 
Specifies that the input or output file détined by this DTFPT declarative macro is 
~to be processed in binary mode. Record format must be fixed, unblocked. Data 
~ may be translated on input or output, but not shifted. On input files, all null 
characters occurring after the first non-null on the 1ape are transferred to main 

— storage. | , - 





> has been 





If the MODE keyword is omitted, data management assumes | 
_ specified us 7.5.2.2). | 


17.5.2.2. Highlights of the Character Mode (MODE=STD) 
The character (nonbinary, or standard) mode of paper tape data management is intended 


for use with 5- through 7-level tapes in 11/16, 7/8, and 1-inch widths. The 7/8-inch 
width is limited to read-only processing. 
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In the character mode of processing, you may specify either the fixed, unblocked record 
format, or the variable-length, undefined format (17.5.1.2). For input files with undefined 
records, you must wire the program connector board to specify the end-of-record delimiter, 
and you may specify a record size register,. into which data management loads the length 
of each record it reads in (17.5.1.6). For output files containing undefined records; the 
RECSIZE register is not optional; you must specify it and load it yourself with record length 
before you issue the PUT imperative macro to punch each record into the tape. You must 
also specify the end-of-record delimiter (using the EORCHAR keyword), which data 
management places at the end of each undefined record to cause tape motion to stop 
when this character is encountered after reading the record (17.5.6). 


To allow more characters to be encoded on paper tape than would otherwise be possible 
with fewer than eight levels or tracks, data management provides a letter- and figure- 
shifting capability, described in detail with the keyword parameters that implement it 
(FSCAN, LSCAN, FTRANS, LTRANS, and SCAN in 17.5.3 and 17.5.5). Data management 
handles insertion of shift characters on output and deletes shift codes on input, translating 
intervening data. You specify the shift codes,.which. may be any of the codes that you can 
punch on tape with the number of levels (tracks) in use. : 


Through ane TRANS keyword parameter: (17.5. 3.1 and 17.5.3. 2), the character ae is 
provided with a translation capability that :you may use for any but an input file with 
shifted codes. For the latter, a translation capability is provided through the SCAN, 


FTRANS, and LTRANS keywords (17.5.3). For output files with shifted codes, translation is 


performed after inserting shift codes; the shift characters themselves are not translated. 


When you are processing in character mode, you may wire the program connector board 
so that the hardware recognizes one delete. character in input files. lf you need more than 
one delete character, you may specify the remainder of them with the SCAN keyword 
(17.5.3.1), and data management takes care of deleting these. Or you may specify all your 
deletes with the SCAN table and not have a hardware delete. 


Parity signal generation and checking are both facilitated in the character mode of 
processing. You may wire the program connector board in the 0920 paper tape subsystem 
to punch an odd or even parity track on an output tape, or to check a parity ‘track, again 
odd or even, that has been punched into an input tape. You. may connect any. photocell or 
punch actuator to any memory bit, except the most significant bit, of a byte in main 
storage. The parity signals are generated within the subsystem; when you are punching, 
the parity signal generated is based on all eight bits of the byte in main storage, even 
though fewer than seven nen. are actually being ps in the paper tape. 


When the hardware detects an odd or even parity error on a character of an input: record: 
the most significant bit of the byte in main storage that represents the character is set to 
binary 1, and data management performs the error processing detailed in 17.5.9. 


é % 
k 4 


Se eet 
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ee Parameter MODE: 





Species: that the mous or output file defined by this. DTFPT. declarative macro is" 
to be processed in the standard, nonbinary (character) mode. You can read and 
punch tapes with from five to seven data levels and may use either fixed, 
unblocked .or undefined record format. You may suppress parity signal punching 
or checking or use the hardware to punch an odd or even parity signal on output 
tape or check parity on an. input tape: In character mode, you may wire the. 
program connector board so that the hardware recognizes one delete character 
and the end-of-record stop character. Null or delete characters.in this mode are ~ 
never transferred to main storage. Data nay. be translated on oe or eae and 
may contain ersee codes. 


17.5.3. Letter/Figure Shifting and Translation, acl Files in Character Mode (SCAN, 
LTRANS, Fe is | 


The ister /fuure shifting capability that data management provides you for use in: 
character mode processing (MODE=STD) allows ‘more data and control characters to be 
represented by the hole patterns you can punch:in tape than would be possible without it. . 


Consider the 5-level paper tape which can offer only 25 distinct combinations of punches 
in its five tracks. These 32 hole patterns are enough to cover one case of the alphabet, but 
not the 10 numbers in addition — and this leaves out a null, a delete, and any other. 
characters you might need. 


If you assign two of the 32 hole patterns to the null and delete characters however, and 
two of the remaining 30 to shift codes (one the “‘letter shift’, the other the ‘figure shift’’), 
you have 28 patterns left for representing data. (Shift codes may be any of the 32.) But 
these 28 hole patterns can now represent 56 characters, if. you establish that each pattern 
represents one character when it follows the letter shift code on a tape, but a second 
character when it follows the figure shift. This is exactly what you do with the SCAN, 
FTRANS, and LTRANS keywords in your DTFPT macro, .with which you specify scan and 
translation tables for shifted input files. You can then handle one case of the alphabet, 10 
numerals, and 20 other characters as well. You may place: cece Ries eng any. symbols 
in e/ther table; it makes.no difference. to data management. - 


One reason this is possible is that, although data is encoded on tape in a 5-hole system, 
you are representing it in main storage in an 8-bit system. One convention in OS/3 is 
data management's assumption that the first record on every paper tape begins with a 
figure’: one of the 28 characters that you have decided may be represented by the hole 
patterns that follow the figure shift code on paper tape. However, if your first record 
actually begins with a “‘letter’’ (one of the other 28 characters that the same set of hole 
patterns may stand for), the letter shift code must be the first non-null character on the 
tape. Data management automatically punches this on output tapes for you. 


Another circumstance making character shifting and translation easier in OS/3 is that 
data management implements these with the BAL trans/ate (TR) instruction and trans/ate 
and test (TRT) instruction. Both of these rely on the ordering of the 256 configurations 
possible in an 8-bit system that is shown in the EBCDIC columns of Table C—1, and your 
scan and translation tables should be based on the same order of character positions. 
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For paper tape input files with shifted codes, in character mode, data: management deletes 
the shift codes it encounters in input records and translates the data between them. (For 
output files, data management inserts the shift codes; this is described in 17.5.5.) The 
shift codes you use are entirely up to you; you may select any of the hole patterns that 
may be contained in ane number of sovels: in le ‘tape you: ‘are using: . 





When you have. a dueiiea the fixed, bnblocked: Facer: aoe  (RECFORM= for a 
file containing shift codes, note that your. records on paper tape are not actually fixed in 
length.. Usually, each has been made longer by the insertion of one or.more shift codes 
and.thus exceeds: the fixed: length your record had when you provided it to data 
ee to ‘be pinehec wot an Hiustration bub me refer macK to. Figure 17—5.) 


When you are processing fixed, unblocked fecords uit chittad characters, however you 
can make for more efficient processing by reserving storage areas for |/O buffers that are 
somewhat larger than the fixed length you provide to data management with your 


specification of the BLKSIZE keyword parameter. When ‘you do so for an input file, data. 


management is able to read in more characters at a time; the delete and shift characters 
are removed, shifted characters are translated as required (and additional tape reads 


performed, if necessary), until the number of data characters in the buffer equals your | 


BLKSIZE specification. Then the data is made available to’ you in the buffer, or moved to 
your work area. To specify this: procedure, which speeds up processing by permitting fewer 
1/O operations to be issued by data pened sole “peo the os neywore in 
your DTFPT macro: sees 5: 1. 5). gen . ‘ 


Konaced Pavanieter: SCAN: - oe we Bes 


SCAN=symbol 


Specifies the symbolic:address of your input file shift code scan table. Required 
in character mode (MODE=STD) for input files with shift codes; the FTRANS and — 


- LTRANS keywords must: BISe: be epeciticn MENG OF the: siesine table especie 
bas wel are ane shift cess 


he optional use of he SCAN table in character mode is: to epeeitya one or more. 


.. delete characters (instead of or in addition to the one delete character you may 


-s specify by wiring the-program connector board, which you then do not include in. 


-- the: SCAN table). Whensyou use the’SCAN table for deletion only, you do not 
specify the FTRANS or. LTRANS keyword; but you may ‘specify the TRANS 
keyword (17.5.3.1). 


i 


om 
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The SCAN table, whose address’is specified by symbo/, need be only as long as 


- .the number of ‘paper tapé codes in the:set to be: read: It contains a 1=byte entry 


for each of these; all are hexadecimal OO except those used to specify the figure 
shift character; the letter shift character, and the.“‘software’’ delete characters (if 
any — there ney be one, none, ‘or Ee inany): ane: nonzero: rentries, in. the ‘SCAN table 
are: ee ee he eis ae : 


Hexadecimal: . sida 
Code Use 


04. - Defines the figure. shift character; is placed in the byte 
. -- . ‘position of the Mana that eorrespouds: to the. figure shift 

-. code » A ete 
08 _ Defines the letter shift character; is placed in the table in 


the Byte lial ta to aug eee cane code 


OG an 28s.< ladicatsee a character to ba, asietad: by. data managoiieAt 
(This “software” delete is in addition to or instead of the 
“hardware” delete character that may be specified by 
wiring on the program connector: board):-There may :be. 
many software delete characters specified in the SCAN 
table; you may specify deletes with or wom the: use of 
ca: | neKaNete aoNete chanel Proee d 


Refer to tHe esdine Bene. that ‘sllaws the ee iene at ae FTRANS and 
LTRANS keywords for an explanation of the SCAN table. See also 17.5.3.1 for a 


» description of the use of the SCAN ata to. delete characters rom records 


Keyword 


bigeessed in saeee mode ee ee 


eee 
bo if 


Pa rameter FTRANS: 


_ FTRANS= Sabai: - aod. cian fem eehct . dee, Oe 


Specifies the symbolic Bddiace: oh your meer t file shaGe franslation table: required 
(with the SCAN and LTRANS keywords) to process input files in the character 
mode -(MODE=S1B) that. contain. shifted chatacters: The label of the translation 
ia al ae 4 ee, Rigen Bs es pares 





The: fanelation: <abie. Sains the: cdetésponderice: between a characiet that is 
punched after the figure shift character on tape. .and the 8-bit code that data 
management is to place in your data area. Each position in the table corresponds 


_ to a different hole pattern onthe :tape, beginning. with hexadecimal OO (null, 
~ which is never transferred into main-storage, but simply marks the first position 


in the table) and extending through hexadecimal 1F, 3F, or 7F, depending on the 
level of tape you are using. 
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The FTRANS table contains a 1-byte entry for each paper tape hole-pattern in the 
set to be read; all entries are hexadecimal OO except those in the positions for 


‘the hole patterns that may follow the figure shift character on tape. The 1-byte 


entries for these hole-patterns may be the hexadecimal digits for the 10 EBCDIC 


_ numeral graphics’ (F1, F2, and so on);.on the other hand, they may also be any 


codes of your choosing: alphabet, punctuation, ASCII numerals, or whatever you 
have decided will be ‘figures’. (In the coding example that follows the 
description of the LTRANS keyword, the codes are hexadecimal F1, F2, etc, for 
the EBCDIC numerics.) 


The FTRANS keyword should be specified only for files processed in character 
mode (MODE=STD);. it is ignored if you specify it for binary mode. You must not 
specify it with the TRANS keyword; if you. do, both FTRANS and TRANS are 
ignored. In either case, a diagnostic message appears in the DTFPT macro 
eapansien) in yous assembiy listing. 


The aseembler generates an EXTRN pseudo-op code for symbo/, which allows 


~ you to assemble your figure translation. table separately from the DTF if you 


Keyword 


want. 


Parameter LTRANS: 


LTRANS=symbol 


Specifies the symbolic address of your input file letter translation table; required 
(with the SCAN and FTRANS keywords) to process sa files in the character 
mode {MODE=STD) with puted Ehat agers 


The translation table, whinge label is eyinbal contains a 1-byte entry for each 
paper tape code in the set to be read; all are hexadecimal O00 except those used 
to specify which tape codes follow the letter shift character on tape and therefore 
are to be translated as “letters.” The 1-byte entries for these tape codes may be 
the hexadecimal digits for the EBCDIC graphics desired (see Table C—1) or, as a 
matter of convenience, their character representation. On the other hand, they 
may be anything you want to designate as “‘letters.” 


*¢ 


~The ‘LTRANS ‘keyword should be specified only for files processed in character 


mode (MODE=STD); it is ignored if you specify it for binary mode. You must not 
specify it with the TRANS keyword; if you do, both LTRANS and TRANS are 
ignored (as well.as SCAN and FTRANS, if these are specified). In either case, an 
error message appears in the DTFPT.macro expansion in your assembly listing. 


~The assembler generates an EXTRN pseudo-op code for symbol; therefore, you 
may assemble the letter translation table Beparately from the DTF if you have 
_.reason to. as 


The following coding example illustrates how you might devise scan and letter/figure 
translation tables for an input file contained on 5-track paper tape, which provides only 32 
possible hole patterns. The entirely arbitrary example assumes that you have decided on 
the following correspondences to the paper tape codes, represented by their hexadecimal 
positions, OO through 1F: 


é 
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Hexadecimal Code Character 
Gye 00 : 4 “null | 
01 enatiak 1G. “etters” (A-Z) ; 

1D 3 letter shift code 

1E | | _ | figure shift code 

1F af - delete 
01 through 09 pe | “figures” (1 through 9). *- 
a “figure” (0) a 


Having decided that you need only one delete character, you take care of it by wiring the 
program connector board, and therefore do not specify it as a software delete in the SCAN 
table. Tas pet ate? 


Example: 
‘LABEL =» AOPERATIONA > omhanc TS A COMMENTS 
1 10 16 fy : : 
I, Py AP] fA, | (OTP the D D ; 
Pda etgre a aoa LLY Pit if: = NIP : sel i aati thy pt dt 
hoe Ho) tee ane S.C anh lpi: nee | | 
Posted tii. | TRANS. ETRIAN 
[osueenaneeenn RANIS LT RAN 
Pian eee & wee i] 
Hele ieee ape 
SCANI!.. | Ds... | bo 
Soi |e. | h2 obo c ane | | ? 
poe Mth 010:' 
Pees 7 cee 
eee ee | i. i 
pel i 9 FLLE.2E bE ZEBIES 
arma were Bb STomee ey Ane to te 
Aeon eke 2 omere a” ‘£0, " He Co rc CO Ln SU EM Yee one WRT We er Oy Cn Una Co a VOW ne Or cel 
Ser Ded iced Eve PLCTE ee ae 
7ILTRANSL. | DS... | lo : 
ia ete IDC os Lal Oo! ics 
Blaera l | ies PLO ARGH eel : 
faa | pe. | Cr.0. kK LANOP RST ' err 
Qo ti | pe 1 | ets, Suvinxy 
poe LD - 3,010,’ 
Pernt 2 ree 
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This is part of the DTFPT declarative macro defining an input paper tape file, 
PAPTAP1. Note that it is processed in character mode; letter/figure shifting is 
possible only in this mode. Keywords not:relevant to the example are not shown. 


SCAN1 is the label of the shift: code scan, table; you assign a 32-byte length 
attribute to this symbol because there are 32 possible codes on a 5-level paper 
tape. You have equated this symbol to the SCAN keyword in the DTF. 


You have placed the hexadecimal code 08 in the 30th byte position in the table; 
this corresponds to the position of the letter shift code, 1D. In the next byte of 
the table, corresponding to 1E; you ‘place the hexadecimal code 04 to designate 
1E as the figure shift code. All other positions in the SCAN table contain the 
hexadecimal code OO; you have omitted the code OC because you have no need 
for a software delete. 


tts 


: "FTRANS1 is is. aie: label on the. hauee franciation tables ike he SCAN fable: it is” 532 


bytes long. You have equated this symbol to the FTRANS keyword in the DTF.. 


Having assigned the 1-byte hexadecimal entry OO to the first byte of the.table.(to 
take care of the null character ee you then are the entries Fl, F2, 


= graphics nfs through | 9. 


Assigning nexadeeinial 00 t to the. nextis seven. Fi betes’ you assign vehes enna FO to the 
. Next byte. Thus the numeral zero is represented on. tape by the punch pattern 
‘corresponding to the hexadecimal. position. 11,. ‘when 11 follows the figure shift 
code, 1E. As indicated by the assignment of. hexadécimal 00-to the 14 remaining 
‘bytes of the table, there are no ‘further characters tor De PPepisceuted BY tape 


- codes that rOONN: the e igure shift code. 


LTRANS|, ieusiods to the LTRANS cewert in. the: DTF, is the label of the letter 
‘translation table for: ‘this: ‘input paper tape file; ‘it also. has a length attribute of 32 
bytes. 


. ha 


_ Again, the first byte ‘of the table is assigned the entry 001 6 begause this position 


is for the null character. To the next 10 positions, you assign the first 10 letters 


of the alphabet, declaring the string is a 10- yt: character Constant for 


convenience of documentation. 


The next 10 being assigned in the. same way, you conclude your assignment of 


_ the 28 available ‘‘letter’’ characters with eight more. The 7th is the period (.), and 
the 8th is the blank, to be represented on tape by» the pattern in hexadecimal 


position 1C. The translation table concludes with hexadecimal OO being assigned 
to the last three bytes; these three bytes (1D, 1, and. 1F) have been dedicated to 


- the letter shift code, the figure shift code, and the ° ‘Hardware’ delete character. 


com tN 
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The foregoing example assumes that you have not wired the program connector board in 
order to change the correspondence between hole patterns-on paper tape and those data 
management encounters in main storage. As you know, you may connect any bit in main 
storage to any hole position on tape; whatever you do has a definite effect on the. layout 
and content of your FTRANS and LTRANS tables and how the characters | on tape are 
ultimately represented in your buffer. | 


Another point to be made is that the codes corresponding: to shift and delete characters 
are not translated by either the FTRANS or the LTRANS table. The entries in these tables 
corresponding to the shift and delete codes. may be hexadecimal S or ay code: they are 
simply used to fill out the table completely. _ 


17.5.3.1. Character Deletion, Input | Files, in 1 Binary or Character Mode 
(SCAN, TRANS) | 


As previously noted (17.5.3), an optional use of the SCAN keyword parameter is to specify 
a SCAN table that is dedicated to assigning one or more. software delete characters, to be 
removed by data management from records read in from input paper tape files in character 
mode (MODE=STD). These software deletes are usually in addition to the hardware delete 
that you specify with the wired program connector board; however, you may specify all of 
your deletes in the SCAN table. When you dedicate the SCAN table to character, deletion 
alone, you. do not specify the FTRANS and PANS p Reneords: but ou may een the 
TRANS keyword paramclel: ates i ey. ane 


In. addition to this use, you. "may ee the: SCAN eyed. paramedian | in. the. DTFPT 
declarative macro, not. only for a file processed in the character mode (MODE=STD), but 
also for one processed in binary (MODE=BINARY). Doing so is the only means data 
management provides you for automatically deleting characters from records in binary 
input files; as you will recall, you cannot use the program connector board for specifying a 
wired or hardware delete when yous are processing in binary mies (7 2.1. 2). 


When. se SCAN table is ised onl to Smee cahivats asia ac there are. only 
two hexadecimal codes: that may be used for. entries: one is OC, which-you place.in each 
byte position that represents a character to be deleted. The other. hexadecimal entry, 00, 
you place in all the other bytes; these represent characters not to be deleted. The length of 
the table must equal the number of possible hole patterns that.can be. punched .in the 
number of tracks or levels.in your paper.tape: 32 bytes for a.5-level tape,..64 for a 6-level, 
tape, 128 for a 7-level tape,.and 256 bytes for the 8-level tape that is used in binary mode. 


Be 
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In the following coding example, the programmer has specified a 256-byte SCAN table, the 
ao Six: positions of which are BeS9neG to delete enaracters: 


Esarapies 


LABEL AOPERATIONA OPERAND A 


When your data in an input paper tape file requires translation before you process it (if, for 
example, it is encoded in ASCII), but also contains characters to be deleted, you may have 
data management delete them before translation by specifying both the SCAN and the 
TRANS -keywords: in the DTF.’ You may do so for both binary and character mode 
Pigeees ne but must not epecty: the FTRANS or LTRANS keyword. 


In this. use, the . SCAN dabie you Sprovide: may contain only the hexadecimal code OC, 
entered for each character to be deleted before translation, and the hexadecimal code 00, 
entered in the position for each code that is to be translated. In the TRANS table (an 
example of coding a TRANS table is given in 17. 5: iS 2), you may enter arbitrary filler codes 


ore ee 


because you will not See any translations for ieee in your I/O or Work areas. 


17.5.3.2.. Translation for Input cee without Shifted Codes (TRANS) woe 


You may use the TRANS keyword sanawieter to specify a ‘eanelation table for any type of 
file except an input file with shifted characters.. For the limited translation function 


provided for files ‘of every kind, via the FTRANS, LTRANS, and SCAN keywords, see 17.5. 3. : 


For the: use’ of the’ es keyword for output. paper tape files, see 17. 5. 5. 


The TRANS ‘able fats you ‘code for an input file without shifted Sharaciers is a simple 
table, not exceeding 256 bytes in length, prepared in the form. required for the BAL 
translate (TR) instruction. Essentially, it is a string of 1-byte (8-bit) codes that data 
management is to substitute in your |/O or work area for the codes originally read in. The 
number of codes in the string, then, equals the number of unique codes you expect to read 
from paper tape, less the software and hardware delete characters, which of course are 
never presented for translation. 


When your input paper tape file is a binary file (MODE=BINARY), the 8-bit codes originally 
read in are the directly corresponding images of the hole patterns punched in the tape. For 
input files processed in character mode (MODE=STD), the 8-bit configuraitons originally 
placed in the 1/O area are those that result from your wiring of the program connector 
board. In either case, data management uses these as indexes to your TRANS table, 
adding their individual values to the address of the table, and the 8-bit code found at each 
table location thus reached is transferred to the data area to replace the one originally 
encountered. 
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i The following coding example shows how you might devise a TRANS table for an input 

N74 paper tape file (without shifting) processed on 6-level tape in character mode. Assume 
that, of the 64 original tape codes, 26 represent uppercase alphabet, 26 the lowercase, 10 
the numerals, and 2.the null and the delete. You now want to replace the HoWwercase 
letters with uppercase for your processing. 


This is the original assignment of tape codes, which extend rem hexadecimal OO through 


SF: 
-Hexadecimal Code Character _ 
00 all.% &, 
- 01 — 1A sipparcase” aiphabel A-Z | 
1B — 34. lowercase ‘alphabet, a-z 
35 — 3E | numerals, 0-9 
3F delete 


Assume that the delete character is taken care of by wiring the program connector board 
(thus making it a hardware delete); this-leaves 63 characters to. be translated: :- 


oO Example: 
LABEL PERE TIOMD OPERAND | A 
( reansic [ps OC.Le 
t ' 
2 


- 
>. 
~ £5 
> 


r, 


b> 


i 


ek 
=O lo 
ew 
> 
s 


(" 4 
~H) ©&- 
a 
= kK 
rc RS 
ae 
gm - 
= 
OG i 
— 


J 
> 


DON Nm. 
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: | Assigns a 63-byte length attribute to the symbol TRANSLC, which is equated to 
-.the TRANS keyword parameter in the DTFPT declarative macro ) that defines the 


input paper tape file to be translated. 


The ‘null character, hexadecimal OO, is unchanged, but an entry for it is 
necessary in your TRANS table. 


Likewise, the meanings originally assigned to the next 26 codes are unchanged; 
you still want the tape codes 01 through 1A to be translated as uppercase 
alphabet, A-Z. But note that you must confirm this by including the same 
information in your TRANS table as applied when the paper jane file was 
punched on tape. 


Here is the only new information your TRANS table contains: the next 26 tape 
codes (hexadecimal 1B through 34) are now to be translated into the EBCDIC 
uppercase characters, from the lowercase characters that they represent in the 
records on tape. 


The last 10 codes covered by this table are unchanged; they represent still the 
numerals O through 9. There is no entry: for the 64th tape code, as it‘is the 
hardware delete character that your program will never see in the I/O area. 


For further details on the preparation of translation tables to be used for the BAL trans/ate 
(TR) instruction, refer to the assembler user guide, UP-8061 (current version). 


Keyword Parameter TRANS: 


TRANS=symbol. 


Specifies the symbolic address of your rdeanalatlen table for. input or output files, 
where symbol is the label of your table. May be used for all paper tape files 
except input files that. contain shifted characters. . 


_The translation table you code is in the form required for the BAL. trans/ate. (TR) 


instruction. Data management generates an EXTRN pseudo-op for. symbol, so 
that you may assemble your ‘table separately from the DTFPT declarative macro. 


“You must not specify the TRANS keyword when you specify the LTRANS or 


FTRANS keywords (or both). If you do so, an error. message appears in the DTF 


expansion in your assembly listing, and data management ignores the following 


keywords: TRANS, FTRANS, LTRANS, AND SCAN (if the latter is specified). 


You may specify the TRANS keyword with the SCAN keyword for input files in 
binary or character mode, using the SCAN keyword to delete characters that are 
not to be translated (17.5.3.1). 


When you use the TRANS keyword to translate output files with shifted codes, 
the shift codes are not translated (17.5.5). For translating input files with shifted 
codes, use the FTRANS and LTRANS keywords (17.5.3). 
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17.5.4. Specifying the End-of-Tape Routine for Input Files (EOFADDR) 


For every input paper tape file, you must code a routine to handle the end-of-tape 
condition. You.must, also use the EOQFADDR..keyword. parameter in the DTFPT declarative 
macro defining each input file to specify the label of .this..routine to data. management, 
which branches to it automatically whenever end-of-tape is sensed, and when you issue a 
GET imperative. macro -to. an. optional.input file, having specified the OPTION. keyword 
under conditions described in. 17.5.7. You need not assemble your end-of-tape routine 
with the DTF, however: in expanding, your DTF.coding, the assembler generates an EXTRN 
pseudo-op code for the label of this routine, and you may therefore assemble it separately. 


If.you have:only.one.strip of tape to read, your. end-of-tape routine may simply terminate 
file processing by issuing.the CLOSE imperative macro,.as you must.do this whenever you 
have completed all processing (17.4.2). On the other hand, if you need to.read a number of 
strips of tape, you must anticipate that data management branches to your routine at the 
end of each of them, and,that.the paper tape subsystem itself goes: into the, stop: state. If 
you want to return to a routine which has been reading and .processing tapes, you have 
only to branch to.the address contained in register 14, as this.register holds the address of 
the next instruction after the last GET macro you issued. However, if you.want to issue 
any imperative macros in your end-of-tape routine before you use this return address, you 
must remember to store and restore .the contents of. POSITS. 14 to PISSORNe: the. return 
address . At contained at the entry: of. Your routine. eae GR ie 


Remember that, in. “Okder for. you to. read. ihe: next jape: ‘he: ‘Operate must load: it into. hie 
reader. and. -press the RUN. switch on the device. But, if a GET macro is issued to read the 
first record on the newly inserted tape before the. operator can press the RUN. switch, the 
physical IOCS .issues -him-an.operator message at the. system.console (DEVICE XXX STOP 
STATE RU?) to which he must reply “R” to read. (The reply “U". results. in data 
management error processing, 17.5.9.) To avoid having the operator go from the reader to 
the console.to read every tape,.you could program into your end-of-tape routine, a time 
delay von shoul to allow him to mount a tape. 

Recall that, in. ores to. ee a. falee. ane at: ane condiicn being gignalied Esfore ne last 
data character .is read. from. | paper tape, you must PiCviees a 12- ingh, Eepey fape.t trailer 
(17.2.3) “ i Foe oie : paboiael ie aie 


ee 


Keyword Parameter EOFADDR: 


EOFADDR=symbol - ; 
Required for all input files to Seach, ifs label of your ‘routine for handling ihe 
end-of-tape condition, where symbo/.is this label.-The assembler generates an 
EXTRN for: label, so that your end- of-tape routine. may be assembled Separately: 
You must close the paper tape. file when all Processing is completed. ; 


J if you. omit ihe EOFADDR keyword: on ihe DTEPT n macro: tore an input file ine if. a: valid 
.-.. EOFADDR routine is not present on. file OPEN),: data. management does not-open the 
file, but issues error message DM61, sets the D7F error flag (bit (0) and error detected 

In OPEN flag (bit 4) in ffenameC, and branches to your error routine. See 17.5.9. 
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17.5.5. Translation and Letter/Figure Shifting, Output Files (FSCAN, 
sheCAN, TRANS) 


Three additidnat Reraids parameters may come into play in your DIF: wei you have 
output files with shifted codes to’ produce in character mode MODE” SID) 


m= =©6©FSCAN (required), wie sseuifiés the label of your figure scan table for this output 
file. Data management uses the table to ascertain which code-it:is to: punch on tape 
as the /etter shift code, and to select out of your output data the ZrOUDE or charcters 

for translation as “‘figures”’. 


= © LSCAN (also required), which specifies the label of your /etter scan table, used by 
data management in the same way to identify the igure shift code and the groups of 
“letters” in your output data: | 


o TRANS. (optional), which specifies the label oat the Hanelation table you have coded. 
' This table assigns, to each of the characters that will appear in your output data, one 
of the hexadecimal tape codes that can be puncned’ in the HUMPE! of character levels 

: existing in ‘your tape: 


The FSCAN and. LSCAN tables are, in a way, eeirbeale: in hat with the FSCAN table, you 
specify the /etter shift code (which must be nonzero), by placing it in’each position that 
corresponds to a ‘‘letter’’, and indicate, by placing hexadecimal OO in all the other 
positions of the table, which 8-bit configurations in your output data are to be treated as 

“figures” by data management. With the LSCAN table, you specify the figure shift code 
(also nonzero) in each position corresponding to a “‘figure’’ and indicate, by hexadecimal 
OO jin their positions, those configurations that are to be treated as “‘letters.’"” These two 
scan tables, between them, must provide a 1-byte entry for every 8-bit pattern that you 
may place in an |/O or work.area to be punched on tape. Both scan tables are prepared in 
the format expected as operand 2 of the BAL translate and test (TRT) instruction. 


If you specify the TRANS keyword, you code the TRANS table in the format expected by 
the BAL trans/ate (TR) instruction, assigning a hexadecimal tape code to each of the 256 
possible 8-bit patterns that may appear in your output. To all remaining 8-bit 
configurations, which are not to be presented in your output data (this includes the 
EORCHAR stop character and the two shift codes which data management punches but 
never translates), you could assign the same tape code. This code may be the one that you 
will insert in your TRANS table to represent the nonprinting EBCDIC graphic character 
foppesite hexadecimal 40 in Table c—1), but you could use some other code. © 


The TRANS Revauid isnot eats: to produce output files with letter/figure shifting, but 
its use is a great convenience, especially with 5-level tape. If you do not use a TRANS 
table, you must work entirely with the data characters that you can punch directly on tape. 
This means that, with a 5-level tape code, you can have only the hexadecimal codes O01 
through 1F in your data buffers. On the other hand, using a TRANS table allows you to 
work in a more convenient code — EBCDIC is only one exampe — and still use 5-level 
ape 


Pe 
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For full details on the preparation of tables to be used as operands of the BAL trans/ate 
(TR) and translate and test (TRT) instructions, refer to the assembler user guide, UP-8061 
(current version), but first consider the two following coding examples, which are based on 
these assumptions: os a —_ 


= Your output tape has five levels, offering 32 hole patterns; these patterns are to be 
represented in your translation and scan tables, and on the program connector board, 
by the hexadecimal codes OO through 1F. 


= You have 37 EBCDIC characters for which you will present 8-bit codes in your output 
data. These are the 26 uppercase alphabet characters (A-Z), plus the nonprinting 
space character (these will constitute your “‘letters’’) and the 10 numerals (0-9) (these 
will constitute your ‘‘figures’’). 


= You will use the hexadecimal tape code OO to represent the null character, 1B for the 
end-of-record stop character, 1C for the nonprinting space character, 1D for the letter 
shift code, 1E for the figure shift code, and 1F for the delete character. 


Although you may not expect to output any delete characters when you create your paper 
tape file, you probably intend to use them in routine processing of the file, and therefore 
must provide room for at least one delete character in your initial assignment of codes. 
(Later for input processing, you may specify one delete with the program connector board 
or one or more with the SCAN keyword parameter.) 


You must specify the end-of-record stop character with the EORCHAR keyword of the DTF 
for this output file; data management automatically punches this after the last data 
character in each undefined record (17.5.6). 


Thus, the following correspondences will be used: 


= @~= Letters: 

Hexadecimal Hexadecimal 
Graphic Representation Tape Code, After the 
Symbol in I/O Area Letter Shift Code, 1D 

A C1 01 

B C2 02 

C C3 03 

D C4 04 

E C5 05 

F C6 06 


G C7 07 
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Graphic 
. Symbol 


H 


JO° wa Se 


<« x S$ < CA WDE VD 


N 


SP 


Hexadecimal... 
- Representation 


.in I/O Area» 


C8 
¢9 
D1 
a 
D3 
D4 
DS 
D6 
ae 
‘DB 
eee 
E2 
E3 
E4 
ES 
EG 
E7 
Eg 
EQ 


40 
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. Hexadecimal.) 2 > .. 
Tape Code, After the 
Letter Shift Code, 1D 
08 
7 OB | 
oc 
OD 
OE 
OF 
; 10 
1 
12 
13 
 414— 
15 
16 
18 
19 
1A 


1C 


17-52.. + 
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@ Figures: 


Hexadecimal - Hexadecimal - - 
Graphic _ Representation Tape Code, After the 
Symbol in the I/O Area’ Figure Shift Code, 1E 

0 FO «#46 | 
1 FL OV: 
2 F200 02 
3 F3 | 03 
4 F4 04 
Dy 7 FB | 05 
i 2 fe SFT ee o7 
9. | F8 : | _ ~—08- 


9 F9 09 


In this seinples any 8-bit Peatiguecnions’ other than thes that you present in the 1/O area 
are to be punched as the nonprinting SP character: that is, following the letter shift code, 
as 1C. Taking its cue from the result of using the FSCAN ee on yout: data, data 
management inserts the letter shift code automatically. 


The end-of-record-stop character, 1B, does not require either shift code; you must always 
be sure that neither it, nor. the code 1C, nor either of the shift codes, ever epbeats in your 
output data for translation. : 


The first of the Sains examapies ameusees your DTFPT déctarative i macro and your TRANS 
table; the second is devoted to your FSCAN and LSCAN tables. : 


Example: 


-' COMMENTS 


= 
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Example (cont): 





COMMENTS 


~ 
Ld 
ow 
o 


S KS lia 

a 

6 

CG 
en 
ee 

9 

' 








Fpeebie 


This is part of your DTFPT declarative macro for the output paper tape file 
PAPTAP2, which is to be processed in character mode (MODE=STD). As 
PAPTAP2 contains records in undefined record format, you must specify the end- 
of-record stop character, which data management punches automatically after 
each record on tape, with the EORCHAR keyword parameter (17.5.6); this is the 
hexadecimal code 1B. The required BLKSIZE, IOAREA1, and RECSIZE 
specifications, as well as other keyword parameters not relevant to this example, 
are not shown. 


You assign a length attribute of 256 bytes to the symbol TRANS2, thus 


embracing. the following. define constant (DC) statements. You have equated 


-. -TRANS2 to the TRANS keyword parameter in your DTF; thus the DC statements 
- -constitute your translation table for the eo tape file PAPTAP2. It covers the 


256 positions of Table C—1. 


To the first 193 positions of Table C—1 (decimal O through 192), you assign the 


tape hexadecimal code 1C. Note that the nonprinting EBCDIC. space character 


(hexadecimal 40) is embedded in this 193-byte string; because it is, the effect. of 
your specification is that any of the first 193 EBCDIC characters (if they appear in 
your. output data) are to be represented on ls by the hole- pene chosen to 
represent the space. a $y : 


To the next nine positions in the TRANS table (those corresponding in Table C—1 
to the EBCDIC graphics for the alphabetic characters A through I), you assign the 


tape codes 01, 02, and so forth, through 09. 


The next seven positions are not used, and any 8-bit. configu ations from this 


part of me table will be represented on tape by the space code, Ve 


. To the next string of nine alphabetic characters (J. through R),. you assign the 


tape codes OA, OB, and so forth, through 12. 


Eight unused positions follow these. 


SER 
as 


ae 
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The last eight alphabetic characters, S through Z, are assigned the tape codes 13 


_ through 1A. Tape codes 1B and 1C already have their assignments; codes 1D 


and.1E will be assigned with the FSCAN and LSCAN tables, as: described in the 


~ . next coding example. You have determined that the tape code 1F is to represent 


: 11. 


one delete character, but, because you will not use it in this output file and 


because (like 1D and 1E) it is. not to be translated, you do not include a 
translation for it in the TRANS table. 


The next six table positions é are also st dite ae Space code, 1C. 


. To represent ihe 10 EBCDIC numerics in your output datae you assign the 10 


tape codes shown here. These are the second assignments for the tape codes in 
question, which have these meanings when they follow the figure shift code on 
tape? and the Brevieusly: assigned ones when they follow the letter shift code. 


The last six positions of Table ae are e provided for di assigning the space code, 
‘TG, oi | 


The second coding example discusses the figure and letter scan tables you prepare for the 
same file. Remember that you need not assemble them, nor the translation table, with the 
DTF because an. EXTRN pseudo-op is generated for the label of each of them. — 





Example: 
LABEL TREERATIONS OPERAND 
2 
“i rare The TE 256, ae 
Bl sive state hoe lI 27.%Lt LD. ea 
cca DCI MPO GetCiae 1 
Sei | ee 6.400,’ ai 
ieee Ghana AN eae els iy 
éLsc ANZ... | DS... | OCL25¢ Wi 
Ao ti | ie. | ki240:'.0.0." a 
(Bb ee hd DG [Tox he! 
qt pe. | ke 500’ Hl 
Gre ied te hee ae i 
NOTES: 
. You assign a length attribute of 256 bytes to. the symbolic address. FSCAN2, the 


N 


symbol you equated to the FSCAN keyword parameter in the DTF. This attribute 
embraces the four DC statements following it, and these constitute your figure 
scan table for the output file PAPTAP2. ia ee 


The first 27 bytes of the figure scan table, covered by this define constant (DC) 
statement, contain the 1-byte hexadecimal entry 1D, which, solely because it is a 
nonzero entry, specifies to data management that the code 1D is the /etter shift 
code. |t must appear in each byte position of the scan table that represents a 
“letter’’. 
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-. .Because the first 27 positions of Table C—1 do not correspond to any EBCDIC 
'. graphics, letters or otherwise, it may occur to you to question why the FSCAN 


table shows these as letter positions. The reason is that they are all to be 


_represented on tape by the same code, 1C, which you have also assigned to the 
~ nonprint SP character in your TRANS table. Because you have included the SP 


character among your “letters”, its code, 1C,. must follow the letter shift code on 


tape. 


Other than the.-letter shift code, the only entry that you use in the figure scan 
table is hexadecimal OO; this code must be entered in every byte position that 
does: not representa “‘letter’’. Not all..of these will necessarily be ‘‘figures’’, of 


-. Course, but. all of the on ‘codes will, be in this SuDSer 


eli: the next cas; you. ‘insert he ‘Kevadesimial code OO to fndicate to data 


management that the corresponding tape code, hexadecimal 1B, is not a “‘letter’’. 


(It.is also not a ‘figure’; recall that 1B is specified to data. management, via the 


EORCHAR keyword in your DTF, as the end-of-record stop character. This has no 


translation, requires no shift code, and sroule never occur in myoul output cate 10 


Heneralion, ). 


| THe next: 212 bytes also contain the’ later shift node. ‘1D, eee eee that the tape 


codes in these positions represent “‘letters’’. These include not only your 26 


EBCDIC alphabetic symbols, but also 185 substitutions of this graphic for every: 


other character in this set of 21 2, all of which must occur on tape after the letter 
shift code. 


. The haxadécinial code 00 in each of the last~ 16 bytes of the figure scan table 
- shows that these do not represent © ‘letters”’. Recall that ony the first 10 of these 


_are actually to be translated as “figures”. 


When. ‘your output data is examined aad tested ey data manageiient, character 


by character, your data serves, essentially, ‘as operand 1, and me ae table as 
operand. 2, of the translate and test (TRT). instruction. sae ; 


So long” as any of ‘the 8-bit configurations in decimal positions 240 through 255 
of Table C—1 is encountered in your output data, or the one in decimal position 
27 (this one should never be there, as it-is equated to 1B), the result byte that 


data management locates in the FSCAN table is hexadecimal 00. Scanning may 


continue, and these configurations are selected out for:translation with your 
TRANS table (shown in the preceding coding example) and the translate (TR) 
instruction. | 


The first nonzero result byte that data management encounters in your FSCAN 


table stops the scanning process, the /etter shift code 1D (never translated) is 
placed by data’ management in the |/O area after the last figure translation, and 
then scanning resumes" — but this time’ data management uses your LSCAN 
table in the same ‘way to select the 8-bit configuration, ‘or group of 
configurations, to submit for translation by your TRANS table. ~— 


for, 
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You assign a 256-byte length attribute to the symbol.LSCAN2, which you have 
equated to the LSCAN keyword in the DTF. This length embraces the subsequent 
DC statements, een constitute sud fetter: scan ane for the: output file 


~ PAPTAP2: 


‘ “In each of tbe, first 240 Bytes of the. scan table, you enter the hexadecimal value 
~00. When these result bytes are tested by data management, using the TRT 


_ instruction, the ~all-zero. pattern each contains allows the scanning and the 
“~-< translation processes to continue, with your TRANS table and the TR instruction. 
_ These 240 bytes include both shift codes, the delete, andthe end-of-record stop; 


except for these (which should. never appear in your output data for translation), 
the 240 bytes represent “‘letters’’, and therefore their translations should follow 


-- the letter shift code data management has already punched into the tape. Recall, 


‘however, that most of these translations are the ‘‘dead-end” substitutions of the 


space character:code, 1C,:for' everything but the 26 alphabetic characters and the © 
space itself. 


You enter the figure shift code, 1E, into each of thé next 10 bytes fascial 
positions 240 through 249 in Table C—1) to designate these ‘positions as 


“figures”. Because 1E is a nonzero entry ina letter scan table, data management 


-. immediately: recognizes it as the figure shift code. When any of these’10 bytes is 
-..encountered in. this LSCAN table by’ data management's use. of the TRT 


instruction on a byte of your output data, the scanning process stops. Data 
management first punches the figure shift code on tape, then punches the 


. correct translation, and, having shifted aon this scan table pach to the FSCAN 
‘table, resumes scanning with it." ee? Sere, 


ere rd 


. The last six bytes. of.the LSCAN table :contain hexadecimal OO; the “dead-end” 


translation process continues if any of these bytes is reached by data 
menegement 


Parameter FSCAN: 


a FSCAN=symbol 


* Specifies the label of a: figure « scan table foi an output paper tape file processed. 
in character modé (MODE=STB), where symbol is the label. The table, which 
may be assembled separately from the DTF, is prepared in the form required for 
operand 2 of the BAL trans/ate and test (TRT) instruction; it must contain a 1- 
byte entry for each 8-bit configuration that you might place in an: I/O or work 





~area to ‘be punched on. tape. Entries in the FSCAN: table corresponding to 


“letters’’ must contain’ the nonzero hexadecimal pou for ae letter shift 


"character; all others: must ‘contain hexadecimal 00. 


‘s ‘The FSCAN. keyword must be ‘specified with the LSCAN keyword, to produag 





). If only one of 


‘these two: keywords is spatified, a diagnostic message “appears - in the DTF 


assembly listing, and the: specification is ignored. If specified when processing is 
in binary mode (MODE=BINARY), a diagnostic appears in the DTF assembly 
listing, and the specification is ignored. 
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ney word Parameter en 


~ LSCAN=symbol | 

Specifies the label of a letter stan table for an Sutput paper ‘08 file processed in 
character mode (MODE=$10), where symbo/ is the label. The table, which may 

_-be assembled: separately from the DTF, is prepared in the form required for 
operand 2 of the BAL trans/ate and test (TRT) instruction; it-must contain a 1- 
byte entry for each 8-bit configuration that you might place in an I/O or work 
area to be punched on tape. Entries in the LSCAN table corresponding to 
“figures’’» must contain the nonzero hexadecimal code for the figure shift 
character; all other must contain hexadecimal 00. fee 





To produce output files with shifted codes in sharaeet fede (MODE= D), 
must specify both the LSCAN keyword and the FSCAN keyword. Refer to the 
foregoing paragraph for the effect of misspecifying these keywords. | 





neyuere Parameter TRANS: 


_ TRANS=symbol * 
: - Specifies the label of a translation table you. have. coded for any paper tape file 
_- but an input file with shifted codes, where symbol is the label. The TRANS table 
.. + may be assembled separately from the DTF and is coded in ne form: required for 
operand 2 of the BAL translate (TR) instruction. 


When the TRANS table is used for pulpit: files with ahitied charactors: the shift 
codes are not translated, but punched automatically by data management. 


Refer to 17.5.3 for details on the use of the TRANS. keyword with input files. 


17.5.5.1. Translation for Unshifted Output Files, Either Mode (TRANS) 


When your output file does not contain shifted characters, but merely requires translation 
from the EBCDIC character data in your I/O or work area to the hexadecimal tape ‘codes 
you can punch in the levels or tracks that exist in your tape, your task is simpler. You 
specify the TRANS keyword in the. DTF and prepare a pirans ation table that is limited to the 
EBCDIC codes you will use. 4 2 


Consider the following example, unieh assumes a 5-level paper tape and records that 
contain only the 26 EBCDIC uppercase alphabet, the space, and three punctuation marks: 
the period and the left and right parentheses. You will not punch out a delete character in 
creating this output file, but will reserve. one tape code, hexadecimal 1F, for punching into 
the tape by other means as a rub-out character and possible specification later as a 
hardware or software delete when you read this.file in future input processing. For the 
null character, you set aside the hexadecimal tape code OO, as before. Your 32 available 
hexadecimal tape codes extend from OO through 1F; you need only the first 234 decimal 
positions. of. Dghle C—1 to cover the EBCDIC eharaciers eroualy Z. : 


ae 
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Example: 
LABEL — AOPERATIONA - OPERAND” ts A 
10 16 
i {CRANSOUT! IDS... | 0.0.2.3: 
>) rare aa ose a 
Shears Liber ela On 
ig pede: (DIC Lb Oe 
<r ewe 0 Vomem Cc mrae 
| ae ee yaa ee 
y, web romeo iar 
Ws OC. PRO | 
(Ol, .i 11.) DC. . | X4L9,'05.0607:0809 0A.OB0COD 
1 a Fee aie ie 
beer TDG | KL OLOFLOLLEZU3 IL SLGs a , 
Bh DC BxE OL ie ete, 
NOTES 
1. You assign a 234-byte length attribute to the symbol TRANSOUT, which is 
_ equated to the TRANS keyword in your DTF (not shown). This length attribute 
| covers the 13 subsequent DC statements, which constitute your translation table. 
2. You insert the hexadecimal tape code OO in the first byte ‘of your TRANS table. 
This is unnecessary for an output file (because this code represents the null 
character, which you do not expect to include in an output record), unless you. 
intend to place a certain (fixed) number of null characters at the end of each 
record in your output to indicate an interrecord gap (17.3. A). If you are not using - 
the null character in this way, ‘you would inclage this byte with, the next (74. 
3. To the next '74 bytes, you assign the fiGxadacimal code 01. Note that the EBCDIC 
space character SP is included in the string: this code, then, represents the 
space and is also’ assigned to all EBCDIC eterecisie not used. 
4. The device constant (DC) statement assigns your next tape code, hexadecimal 02, 
to the EBCDIC period. 
5. ~The ‘EBCDIC -less- than. character is’ assigned the same nonprint code, 
hexadecimal 01, as the other characters to be skipped. 
«C6. The left acne eele is assigned the hexadecimal tape code 03. 
7. Fifteen more EBCDIC codes, unused, are assigned the nonprint code 01. 
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8. Here, the right parenthesis is assigned hexadecimal 04. 
9. Nifiety-nine more EBCDIC codes, through the left brace, are skipped. 


10. To the next nine bytes, representing the EBCDIC. alpfiabatic ‘characters A through 
. |,-are assigned the hexadecimal tape codes 05; 06, and so on, through OD: 


11. The seven subsequent EBCDIC characters, through: the right brace, are assigned 
. hexadecimal O1. = 


abe. These nine tape codes cover the alphabet characters sf through R. 
- 13. Eight more skips. 
-14. The last of the EBCDIC- uppercase alphabet, S: shioighe Z, are ‘assigned: your 


'. . remaining hexadecimal tape codes, ; 7 through. 1E — Jeaving only neeageelna: 
1F, for future use when'a delete: character is neeyeds - 


17.5.6. Specifying the End- of-Record 4 Stop. Character for Output Files: | (EORCHAR) 





When you are processing in. character mode (MODE=3 ) and your: ‘file contains records 
with varying lengths (RECFORM= UNDEF), you have néed of a character. to delimit these 
records. With output files, you-must specify this character with the EQRCHAR keyword for 
data management to punch at the end of each undefined record when you issue the PUT 


macro; recall that you must also designate one general register into which you load the.. 


length of each undefined record before you issue the macro (the RECSIZE register, 
17.5.1.6). a 


The end- -of- record Stop ‘character, ‘causes. tape motion to stop. automatically when this 
character is encountered while an input file containing undefined records is being read. 
‘Recall that, for input, processing, you must specify . this. character by wiring the “program 
connector board (17.2.1. 2). i. | . 


For. output processing, . ‘the character you specify. with the EORCHAR. keyword may be 
represented by any of the tape codes you may punch in the number of tracks on your tape; 
however, you should not use the-null character, nor, in fact, any of the codes to. which you 
have assigned a special meaning (such as the delete, or one of the shift codes). The 
EORCHAR stop. character must be excluded from. translation. tables, as it. has no 
translation, and it must be independent of shift status; therefore, it must also lie outside 
the range of “figures” and ‘ ‘letters’ ‘designated by your scan tables. In fact, you. must take 
pains to exclude the EORCHAR stop from your own output. _ 


For an output file, data management automatically inserts the EORCHAR stop character in 
-your I/O area before it writes the buffer contents out to the punch; your BLKSIZE 
specification must always include one extra byte for it. When an undefined record is 
transferred to your I/O area from an input file, ‘the EORCHAR stop. character. comes with 
it, and the buffer space you reserve must accommodate this byte; however, the record 
length that data management places in your optional RECSIZE register does not include 
the EORCHAR byte. Figures 17—2, 17—3, and 17—4, in 17.3, illustrate these poms 
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Parameter EORCHAR: 


sRORSHED = Ctler we ea ae ee 
* Specifies the end- of-record stip’ character ised to delimit ee utidefined acre 
--. required for output’ files processed in character mode (MODE=STD) when 
~ «~RECFORM=UNDEF: is specified. Here, expression is either an expression of self- 


defining terms or a symbol that is. equated to an expression of self-defining 
terms. 


Data manaueinent oe the sherseter defined with the 5 EORCHAR bevaieia at 
the end of each undefined output record; it is the oe character punenede on tape 


to delimit each Bnoeted recore: 


Bvempies 


LABEL AOPERATIONA OPERAND ono 





Ve 


4 sé 


Spedifiés that® the ‘Hexadecitiial tape’ ‘code 03 is to be punched by” ‘data 
"management as” the end-of- record tae character to delimit each: undefined 
‘ ‘record on tape. oe, Ee 


Specifies that the end-of-record stop character to. be punched by data 


management as ‘a delimiter after each undefined ‘record on ‘tape is the logical 


product (AND) of the EBCDIC character P and the hexadecimal value OF (this 
works: out to be hexadecimal O7).°  - 


Specifies that the end-of-record stop character is the expression of self-defining 
terms equated elsewhere in your program to the symbol CHAREX. The equate 
(EQU) directive for the symbol CHAREX, represented by the last line of coding in 
example 3, makes’ this: example exactly the equivalent of example 1 | 


Notice two points about this way of specifying the EORCHAR kayaerd the scoding 


that contains the” equate’ -(EQU) directive must be” placed outside the’ DTFPT call — 


itself, but it must be assembled with the coding that contains the DTFPT call. The 
assembler does not generate an EXTRN for expression. 
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17.5.7. Specifying Optional File Processing (OPTION) — 


Optional file processing for paper tape input or output files is much the same as for 
punched card files, described in Section 3. As with cards, an ‘‘optional’’ paper tape file is 
one that your program. will not: invariably punch or read every time it is executed; you 
notify.data management that this is the case by specifying the OPTION keyword parameter 
in the DTF defining the file. The specification is simply OPTION=YES. 


If you have specified the keyword, there are two circumstances that result in optional file 
Byeree Py data management: 


m You fave specified the OPT wosticnal parameter mn ‘the. job control DVC statement in 
the device assignment set for the file, and the device is not available at execution 
time; or mos 


m= You have not provided a device assignment set (job control DVC and LFD statements) 
for the file. oo = 


For details on these job control statements, refer to the job control user guide, uUP- 8065 
(current version). 


This is Mina optional file processing of a paper tape file involves: 


= @66lf the file is an input file, the first GET imperative macro you issue to it. results. in an 
immediate branch:to your mandatory end-of-tape routine, the label of which you must 
specify with the EOFADDR keyword (17.5.4). No I/O is performed; you must close the 
file, using the CLOSE macro (17.4.2). | | 


= = If it is an output file, the first PUT macro you issue results in an immediate return to 
your program, at the first instruction. after the PUT macro. No |/O.orders are issued 
by data management. if you | have specified the IOREG or RECSIZE registers, data 
management sets these up so that you may process in exactly the same manner as if 
you were actually punching a paper tape. Again, you must close the file. 


If you have not specified the OPTION ‘keyword parameter, and one ae the foregoing 
circumstances occurs, the paper tape file is not opened by data management. and may not 
be processed. In the error processing that ensues, data management takes the following 
actions: 


- ‘Sets the error in OPEN flag, bit 4 of filenameC 


= Issues error message -DM21 ‘to. the. log: “INVALID OR MISSING DEVICE 
ASSIGNMENT”. 


a Branches to your. error routine or, if none is specified, . returns to you inline: at the 
first instruction after. the OPEN macro you issued to the file. 


# ae 
4 
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lf you do not code an error routine but take an inline return, then all GET or PUT 
imperative macros that your program issues to the file result in further data management 
error PiOgessI NG, as follows: : 


a Data management sets the invalid imperative macro flag, bit Go of filenameC; and 


m =§©>6 IsSues._ error message DM13 to the — “ATTEMPTED ACCESS TO AN UNOPENED 
FILE’. te 


These actions result fovicien? issue of GET or PUT to the file. Because the file has not 
been opened,. you need not issue the CLOSE imperative macro to the file. For further 
details on filenameC and other aspects of data mianagemehts error processing, get to 
the ERROR hoy’, 17.5.9." | | | 


Keyword Parameter OPTION: 


~ OPTION=YES. 

Specifies that the input or output paper tape file defined by this DTFPT 
declarative macro is.an “‘optional’”’ file and is not required to be processed every 
time the program is executed. Data management performs optional file 
processing if this keyword is specified and either no device is assigned to the file, 
or you have specified the OPT positional parameter inthe DVC job control. 
statement for the file and no device is available at execution time. 


_., If you omit the OPTION keyword parameter and one of the foragoins denditions exists, 
~. data management does not open the file, and you may not PIgeee: it. Data 
management. error processing results. : 


17.5.8. Providing a General Register Save Area (SAVAREA) 


In common with the other OS/3 data management systems, paper tape data management 
requires a 72-byte area in main storage, aligned on a nulwere Pounders in which to store 
your general registers while it is processing. me a 


You must align and reserve storage fol fhie: area within your program, ‘but y you ‘Have two 
ways of providing its address to data management: loading its address into general 
register 13 before entering any data‘management imperative, or specifying the label of the 
area via the SAVAREA keyword in your DTF. You need only one general register save area 
per program, but if you specify the SAVAREA keyword in one DTF, you should SPeciny: it in 
all.* 


*It is possible to write a valid program in which you preload register 13 with the address of a save area before you issue any 
imperative macros to a file whose DTF does not contain the SAVAREA keyword, and also, omitting the preload of register 
713, issue imperatives to another file whose DTF does contain the SAVAREA keyword. The program could work; the trick 
might be (in a large program processing numerous files) to be sure which file required which coding. You could not open all 
files with the same OPEN macro, for example, in such a program, nor terminate them all with one CLOSE — and you might 
be hampered in your use of register 13 for the IOREG or RECSIZE register. 
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When you specify the label of the general register save area with this keyword, you free 


register 13 for your own use and may, for example, use. it for your IOREG or RECSIZE. 


register (17.5.1.4 or 17.5.1.6); otherwise, only registers 2 through 12 are yours: Refer to 
1.4 for the content and layout of the save area, which is useful to examine in program 


dumps or snaps. Note that register. 13 is not included; however: if you .want to. see its” 


contents ina snap, yeu must A stadia and load a Specie storage area for them. 


If the SAVAREA keyword is not pieeent. in tne: DTEPT declarative macro, data mananeent 
assumes that you have preloaded register 13 with the address of a fullword-aligned, 72- 
byte general register save area before you issue any imperatives. If you -have-a BAL 
program, therefore, written for some other data. management system: (such as the 
9200/9300) in which you are using register 13 for your own purposes, you may easily 
convert it to run under OS/3. You need merely add a 72-byte register save area, fullword 


aligned, to your program and specify its label to data management win ine Se aee 


keyword. 


Because the assembler, in expanding your DTFPT declarative macro, generates an EXTRN 
pseudo-op for each symbolic label specified via the keywords in‘the DTF, you may 
assemble the coding by which you HoUNe the register save area pecpelete from the coding 
in. mee yee define the ue. 5 Hee ae ¢! | oe “a 


canes Parameter SAVAREA: 
‘SAVAREA=symbo! 
» Specifies the. label of an area defined in main storage, fullword aligned and 72 
-bytes in length, tn which. data. management stores the contents of your user 
general registers while it is processing, where symbo/ is the label. 


Only one such area is required per program, but if you specify the SAVAREA 


keyword in one DTF, you’ should specify it in the DTF for: every file your program 


accesses. 


If the SAVAREA keyword is omitted, data management expects that, before you issue 
any imperative macro to a file, you have preloaded register 13 with the address of a 


72-byte storage area, fullword ghee: in which it saves the contents of yen gener 
by apeled a . a | f 


. If you: specify the SAVAREA. pe sib Fal register. 13° is ‘avaiable for your own uses; - 


however, its contents are not included in the general register’save area for inspection 


‘in a snap-or dump of your program. Refer to 1.4 for the layout and content of this” 


area. 


or 
i ‘ 
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17.5.9. Data Management Error Processing, Paper Tape Files (ERROR) 


When data management detects an error (hardware, software, or logical), ‘it sets one or 

more bits ‘in the error flag byte of your DTF file table, issues the appropriate. numbered 

data management error message to the log; and branches to your error routine. If you 

have not coded a routine for error processing and specified. its label to data management 

with the ERROR: keyword parameter, control returns to you at the normal inline return 

point: the next instruction after the imperative macro just issued. This is the point to 
which data ‘management would have transferred control if no error had occurred, 


When data management branches to your error routine, register 14 contains the addiess 
of the normal return point, to: which you may branch,. after you have completed error 
processing, to resume processing your file. However, if you intend to issue GET or PUT 
imperative macros in your error routine, you must first store the contents of register 14 
and-then, having. issued all. your imperatives; oe Fegister 14 to- its initial value before 
you branch back to your program. 


The error pflag byte is decimal vis 50 in the file table generated by the assembler in its 
expansion of your DTFPT declarative macro; the assembler also generates an EXTRN 
pseudo-op for this byte, assigning it a label that is formed by concatenating the EBCDIC 
character “C” to your 7-byte logical file name — which is why it is called filenameC. \f you 
want to examine it to see what bits were set, you can easily locate filenameC i in a dump of 
your program area, because its address ‘is contained in the allocation map and definitions 
dictionary produced by the linkage editor, or you can include filenameC in a snap taken by 
your error routine; however, it is more useful to access it ‘dynamically. You may do so 
inline or from your error routine, using the label of the error flag byte as the first operand 
of a BAL test under mask (TM) instruction, for example, to determine which bits were set 
so that you may take appropriate action. 


Each of the eight bits in filenameC has a special significance when set to binary 1 as an 
error flag; Table 17—-2 summarizes these meanings. The subsequent paragraphs discuss 
the errors represented in more detall, with actions non should Cons er taking in your error 
routine or elsewhere... ge | : 
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Table 17—2. Significance of Bits in FilenameC, Paper Tape Files - 


Data Management Error Messages 
Issued to Log 


: _ Hexadecimal Binary if are s! . 
if Set Alone Se Alona Significance for DTFPT File 
4000 0000 - DTFerror | : INVALID DTF FIELD, PARAMETER, 
: Oe ne OR PARAMETER COMBINATION ' 


0100 0000 Wrong length error — : WRONG LENGTH ERROR 
DETECTED. 
“2°10 


0001 0000 © Unrecoverable’error = -- DM23: .. UNRECOVERABLE 1/O ERROR 
DETECTED ; 


INVALID IMPERATIVE MACRO/ 
MACRO SEQUENCE ; a: 


0000 0001 | _ Invalid record size 17: INVALID BLOCKSIZE SPECIFIED, 
po | uae ia a ‘or: os 


RECORD:SIZE INVALID 


NOTES: | 

@ The ‘‘Other Bits Set’ column shows only those bits invariably set by data management. Others may also be set, for example, to 
indicate which errors are detected curing OPEN or CLOSE processing: 

@) Bit 4 is. eee set when bit 0i is set. The adi binary configuration of filenameC is 1000 1000, and the ae then containg the 
hexadecimal Value 88. 

B) When bit 4 is set with bit 7, the resulting binary configuration is 0000 1001, and filenameC contains the hexadecimal value 09. 

4) When an unrecoverable error is detected during OPEN processing, bit 4 is also set with bit 3, and filenameC contains the 
hexadecimal value 18. When detected during CLOSE processing, bit 5 is also set with bit 3; filenameC contains hexadecimal 14. 

" #@DITF error (bit O) 


This bit is set by the OPEN transient overlay to indicate that a serious error has been 
detected in your DTF. Data management also issues error message DM61. The error 
detected in OPEN flag (bit 4) will also be set to binary 1. Your file is not marked open 
and cannot be processed. 


The D/F error bit is set when you have not properly specified the BLKSIZE keyword 
parameter (17.5.1.3), have omitted the EOFADDR keyword for an input file (17.5.4), 
have omitted the IOAREA1 keyword (17.5.1.4), or have specified an invalid address in 
the DTF (that is; some label or symbolic address specified in your DTF is an invalid 
address — in this case one that is not within your job region). 


You should check your DTF assembly listing for error flag messages and your linkage 
editor map for unresolved EXTRN symbols. 


se 
POO 


Poe 
f 
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a mereng engen error (bit 1 


‘This bit is set for input files with adctined variable lanai) records; it indicates that 
~data management has filled the |/O buffer withthe number of bytes specified by your 

BLKSIZE specification (shift codes having been removed), but that the hardware has 

-not detected the wired end: of-record oP sc vauactots that gClTnItS each undefined 
; record. ; 


‘The wrong \1ength error flag is sige set Hoe fixed unblocked: aout files if the last record 
on the tape is not a full-sized record (that is, the number of bytes of data yielded by 

_ the final record, stripped of shift characters and deletes, must equal your BENSIZE 
specification, or. you al receive. a ene length error tee 


Data management issues error message DM25. in either. case. on may either stop 
processing and close your file, or process the assumed partial record and. then, 
issuing another GET macro, branch to. the normal return point to continue processing 
remembet ag to store ale restore meget 14 as erequie’: 


_ ‘Unique (parity) error r (bit: 2 


When a earity error Is: “dstected in reading: an ‘input. paper tape, the physical lOCS 
- issues a standard message to the operator, describing and locating the error. The 

operator is able to move the paper tape back to the beginning of the record and to 

retry the command; if the retry is successful, data management does not perform the 
‘error processing set forth here. If the retry effort fails, NOWEVEN, -you mays have 
_ recourse to further reraveny Bie URNS: as ae las 


The unique (parity) error bit is set only for input files, Sr abscced in chakacter ‘mode 
(MODE=STD); the file must have been created with a parity track punched on the 
tape, and the paper tape subsystem must have been set up (using ine program 
connector board) to check the parity track for odd or even. parity. 


Set to binary 1, this bit indicates detection of a parity error in one or more characters 

‘on. tape. Furthermore, each character on which a parity error has been detected has 
its. most significant bit set to binary 1 in main jeterage: ‘Your. optens depend on 

whether your data contains shinted codes. 


Ror files with unshifted data, you have hibe: courses open to you in your error 
routine: s 


— You may stop processing records and close the file. 


— You may continue processing the record 4 Bianeling to ne normal return point, 
at the address contained in. Register 14... 


“=~ You may store register 14 nnd: issue another. GET macro. to: iis the record 
containing bad parity and read in the next. If the next record is free of parity 
errors, you can restore register 14 and branch to the normal return point to 
resume the processing that was interrupted by the initial detection of parity 
error. On the other hand, of course, errors detected in the execution of your 
second GET macro will result in another branch to your error routine. 
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When parity errors are detected on files with shifted characters, however, your 
recovery action is somewhat different. Data management does not perform shift 
-. processing on the. record, but.leaves it in the.1/O. area. (Even though you may have 
specified work area processing, the record is not moved to your work area.) Its. shift 
codes ‘are not removed,:‘nor the software deletes —- nor are the intervening. characters 
translated. Unless:you: want :to: stop processing: and close the file, you must deal with 
the erroneous record in your error routine; to skip this record is risky at best, because 
the shift status is likely to be masked by the pay error, and yew ooo RSeOrds 
oa cannot be assured of: polis Higeeese? paidiaee ; 


a 


| ait you. have specified an VO. index register with the IOREG: eeu 17, 5.1.4), you 


can locate the error:record: by referring to this register. On the other hand, if you have 
specified more than one I/O buffer but do not have an IOREG register, you may refer 


-to the address of. the error record that ‘is contained in filenameD, a 4-byte field, 


...fullword aligned, and addressed by concatenating the ‘EBCDIC character “D" to your 
.7-byte file:name. Do. not mediyor the: contents of filename. 


After locating each sharactar of the facord ‘tint a -patity error and resetting its 
most significant bit to binary O, you may perform the character shifting, in your error 
routine, removing the shift codes and translating the characters between them as 
‘required. You should compress the record and leave: it left-justified in the 1/O area, 
or, if: you. have specified | vote area Brogessing: yous) must myodieet a move the: record to 
aa works area. ee je 1: en pre EP ony 


a You will use your: SCAN. bie as pee 2 of de BAL ae anh test (TRT) 
instruction, and your FTRANS and LTRANS tables as operand 2 of the trans/ate (TR) 
instruction; refer to 17.5.3 for details on the use of these tables and instructions by 


'» data: management...Remember also to take care of removing any ey ste Bernas 


shea Characters you ney encounter in vepe error record. 
Uarecadersble. error (bit 3) : 


This bit, when set to binary 1, indicates that an unrecoverable hardware or software 
- error has been: detected. In most instances, the physical |OCS issues a message to 
-the operator, such:as ‘DEVICE XXX STOP STATE RU?"’. This. message indicates that 
the paper tape subsystem is in the stop state. If the. operator replies “‘U’’ to this 
message, data management branches to your error routine with the unrecoverable 
error bit set and. issues error messges DM23 to the log. Under certain conditions, the 
error detected in OPEN or error detected in CLOSE bit (4 or 5) may also be set. 


Error detected in OPEN (bit 4). 


This. bit is set when any errors are detected during the processing performed by the 


OPEN transients (17.4.1). The file is not opened, and you may not issue any 
imperative macros to process jt. In your error routine, you should not attempt any 
further processing of the file and should terminate aOur Ereghany It-is not necessary 
to issue a mESODE macro. LO: the file. oes Aas 
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Other bits may be set with this bit to indicate which error was detected. For example, 

if you have an invalid DTF, this is detected during OPEN processing, and both bit O 
and bit 4 are set; data management issues error message: DM61. -Or,. if. your 
‘specification of the BLKSIZE or OVBLKSZ keyword is not‘a positive decimal number in 
the range 1 through 4095 (or the OVBLKSZ specification does not exceed block size), 
‘the OPEN transient issues error message DM17, INVALID BLOCKSIZE SPECIFIED, 
and sets both bit 7 and bit 4. Again, if the error detected by the OPEN ‘transient is 
unrecoverable, data management issues error message DM23 and sets both bit 3 and 

~. bit 4. Finally, for the circumstances under which the error in OPEN bit is set mel an 
optional file, tefer to the OPTION keyword, LST aa ig 


If you have not. éoded and specified the ERROR routine, but Sensor error returns 
inline, data management expects that you will check for errors and deal with them 
inline. When you do not do so, therefore, each imperative macro your program issues 
- to process an unopened file results in further data management error procers! ie: This 
elt includes ne the- invalid imperative macro flag (bit = . or 


LE " Error detected in ) CLOSE (bit 5) 


a This bit is "eet winees -errors are. detected atte the processing settdrnied: by the 
. CLOSE transients (17.4.2). Other bits may also be set to indicate whens error: was 
' detected: for example, bit :3 if the error is unrecoverable. ai ee 


CLOSE plocessing is lobar, ane yeu may pepe the nes | 
# ~ Invalid imperative | macro 0 (bit 8) 


oe This bit is set to indicate that you: have ieguée an rinaperondate migarsiies macro to 
process your file (for example, the GET macro.to an output file, or :a CNTRL. macro, 

- which does not exist in OS/3 paper tape’ data. management). In this circumstance, 

~.- data management. also issues: ‘error wusssage ae “INVALID MACRO/MACRO 
«© SEQUENCE”, to the log. a ca ee, : ee ee ee er ae 


This bit is also set if you issue any imperative macro except OPEN to an unopened file 

—:including one that could*not be opened because of an invalid DTF or because of 

some other error detected. during your: OPEN: processing. In this .case; data 

ma nagemenikc issues error messes DM13, ’ > TTEMEAED ACCESS 0 AN OPENED 
. “FILE”. 


" Invalid record size (bit 7) 


This bit is set only when you are processing an output paper. tape. file et contains 
undefined records (RECFORM=UNDEF); it indicates that the number you have placed 

_ in the. mandatory RECSIZE register (17.5.1.6) is negative, zero, or larger than. your 
‘BLKSIZE ‘specification minus one byte (BLKSIZE-1). Data: management does, not: punch 
the record on tape. If this bit is set, data management also issues error message 
DM18, “RECORD SIZE INVALID’. Your error routine should cease processing and 
close the file. 
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17.5. 10. neROcess!ng ASCII Paper ei (SCAN, TREN) 


In 08/3, neither the hv eieel locs. nor paper tape data management: provides automatic 
translation facilities. How data comes in from paper tape and is. represented in main 
storage (and vice versa) .are determined solely: by the way. :you set up your program 
connector board and by the hole patterns on the tape. A hole: on the paper tape Pays 
corresponds to some bit in main ; Storage. 


On the other hand: translation of data, via translation cables that you supply, is always 
possible for every type of file, be it input or output, binary or nonbinary, with or. without 
shifted characters. If you need to read a paper tape that has been punched in ASCII, or to 
punch ASCII characters on tape, you must provide the proper translation tables in your 
program. 


The ASCII code is specified in -American National Standard Code for Information 
Interchange, X3.4—1968, and is.a 128-character, 7-bit code. Another.standard, American 
National Standard Perforated Tape Code for Information Interchange, X3.30—1971, 
specifies the representation of ASCII in perforated tape. The perforations are arranged in 
eight longitudinal tracks, one for each of the seven information levels, and one for parity. 
The bits of :ASCIl are. assigned to specific tracks, and the ASCII character represented by 
each 8-bit pattern is related to its corresponding column and row position in ASCII. The 
parity bit is always recorded on the number 8 track, and provides an even number of holes 
for each character. 


Figure 17—11, adapted from a figure in the standard, depicts a portion of an 8-track paper 
tape on which have been punched a number of ASCIl null characters (NUL — no punches 
except the feed, or sprocket hole), the 10 ASCII numerical characters, and the ASCII delete 
character (DEL). The:rectangles above the diagram of the tape ‘itself relate the standard 
hole patterns punched in the tape to the ASCII character positions in the columns and 
rows. of. the standard: the ASCII DEL character, for example, occupies column 7, row 15; 
the ASCII numeral 9 occupies column 3, row 9. (There is not. shown in these rectangles 
the column/row position (0/0) that is occupied by the ASCII null character, NUL, because 
there are seven of mnese punched in the tape in the figure.) 


The following uals: showing how you Stat code a danslation table and a scan table 
to Teed an ASCII paper tape jin. ere using data management, assumes that: 


2 Your ASCII input file is oi taeees in A bingy mode, and the contents of its records are 
limited to the ten ASCII numerical characters and the ASCII space character. 


= These eleven ASCII characters are to be translated into the corresponding EBCDIC 
es characters for. veut: Pieters Ng in OS/3. ele 


a athe tape also contains the ASCII NUL énaracter and: the Standard delete ahacacter 
* DEL. (Recall that in binary. mode, you must. specify this:as a “‘software delete’’.) 
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= The hexadecimal representations in main storage of the 13 codes punched on the 








ASCII tape are the following: 
Hexadecimal ASCIl Character — 
00 NUL 
20 SP 
30 0 
31 1 
32 2 
33 3 
34 4 
35 5 
36 6 
~e ope a ey @ a 
( 
- 38 8 
39° 9 
TF ie DEL 
Column: i 17 
Row: : Hs | 
ASCII siterea - 
characters ————=— 1 2 3. 4 5 6 7 8 9 DEL ~<——=ASCIil delete 
character 
bi _@ 
b2 e@ 
b3 @ 
FEED « FEED 
ba - e 
b5 ® 
b6 e 
b7 e@ 
CHECK e 
ASCII bit number Paper tape track number 
eee 77 = . Figure 17—11. ‘Portion of ASCII Punched Paper Tape, Showing Correspondence 


Between Hole Patterns and the Bits of the ASCII Code 
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Example: | 






LABEL AOPERATIONA OPERAND - COMMENTS 
10 16 


1 ree "} . 
WINAS GLI. | prep | M = LN P, oe es re ee 


my 
rreeee ert BINARY, Ps ae Sn eae Ae TN eer I SP area eee bX 
RAN = x AiNkk CT : l Ll =a | 2 A 
Ce 
ZITRANSCLT| DS... | [0 | i 
Spt LD 7 He 32,100," ; 
aeeeeane D Mt 40. 
2 LroReL anna Soe EL Ee UCTSTESUSERERETONTETU 
G D XLLO, FOF LFZF3.FHF SE SFIZE SES im 
ee : 
ee ee pre tysie eT ee dy il eh hee ee Dy : 
we vom SOS Wary 4 ESET WY Fl atl A CT Wt es TY YO 
eee SeEeiCreHrereadd 
8D, Dis. | OCLL2i8 ; 1 
Pireire, | PC th 0.0, isi tgun at gids 7“ 
ll... 111.) DC. | & "0G." ; fh atl eee Ae A le ee eka chy wie deka eaels ne coon oe : 
NOTES 

1. This is part of your DTFPT declarative macro, defining an input paper tape file, 
INASCII, processed in binary mode. Required keyword parameters not relevant to 
the example are not shown. 

2. This is the define storage (DS) statement, coded elsewhere in your program, by 
which you assign a 127-byte length attribute to the symbol TRANSCII. Because 
you have equated this symbol to the TRANS keyword parameter in your DTF, 
data management recognizes the following define constant (DC) statements as 
constituting your translation table for this file. The table need not be 128 bytes 
long, even though this is the length of the ASCII code, because the 128th 
character (hexadecimal 7F) is the standard ASCII delete, which you must specify 
as a “software delete’’ to data management, via the SCAN table. Data 
mane geiment will delete this character before translation: | 

3. In the the first. 32 byte positions aE -your ‘eaacietion: table, you insert the 
hexadecimal value OO. This is the common code for both the EBCDIC and the 
ASCII null characters, but note that this statement also substitutes the EBCDIC 
null for each ASCII character in the remaining 31 of the first 32 positions in 
Table C—1. None of these is expected in your input data, and you have no 
translations for them. You might instead have substituted the EBCDIC space — 
but not the delete, because deletion precedes translation. 

4. You substitute the hexadecimal value 40, which represents the EBCDIC space, 
for the ASCIL. space characters, occupying ‘decimal..position 32 (hexadecimal 20) 
in Table C—1. 

5. The next 15 bytes of your TRANS table are also filled with the hexadecimal value 


N 



































00, nullifying ‘any unexpected ASCII maverick codes between the SP character 
and the first of the ASCII numerals. 
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6. Here you substitute ten EBCDIC hexadecimal values; FO, F1,.F2,-and so on, for. 
the hexadecimal values ea in your input cate roe the t ten ganens numeral 
_ eas er i . ine 


ae The: eeivaindat a he ASCII: codes should not epoca in your ano data ana are’ 
hence nullified — except 7F, the standard ASCII delete, which you provide for in 
the following scan table. 


8. This define storage (DS) statement assigns a 128-byte length attribute to the 
symbol DEL7F, which you have equated to the SCAN keyword parameter in your 
DTF. Data management recognizes the next two DC statements as your SCAN 
table for the input file INASCII. This table must be 128 bytes long to include all 
128 characters of oo 


oe te Nou insert the hexadecimal value 00. in the first 427. Paes of this ‘able: Heise : 
'. «this ‘value has nothing to do with. the ASCII NUL character: it ensures that a zero 
_-result-byte ‘is encountered by data management when ‘any of the hexadecimal 
values in the first.127 positions of Table C—1 is.read in your input data,and the 
data is submitted to the BAL trans/ate and test (TRT) instruction. Any of: these’ 
127 characters occurring in your npuE data is eevee for translation, using your 

. table TRANSOM. ae rare ioe GP 


- 10. This.etatemant inserts the hexadecimal value OC-in the, 128th byte of your scan. 
~ table: When the standard ASCIil delete character, hexadecimal /7F, is encountered | 
- .in your data, the .result-byte: data management ,accesses in the scan table 
contains this nonzero value. The character 7F is therefore not translated; instead, 
data management deletes it pBetore eo your next ise of npure data ang thus 
a POMpReSse3” veur rororet a. ca ee eee eo ne ee ae | 


17.6. .COMPARISON OF 0S/3 —s OTHER PAPER TAPE SYSTEMS| 


The OS/3 paper tape data management system is comparable with the paper tape 
systems in SPERRY UNIVAC Operating System/4 (OS/4) data management, SPERRY 
UNIVAC 9200/9300 Series Operating System IO€S, and the IBM System/360 Disk 
Operating System (DOS). The following paragraphs discuss areas of compatibility. 


17.6.1. Compatibility with OS/4 


OS/3 paper tape data management is compatible with the OS/4 paper tape system 

documented in the OS/4 data management system programmer reference, UP-7629 
(current version). The maximum block sizes of the two systems are the same: 4095 bytes. 
The OS/4 ERRO keyword parameter is accepted by OS/3, but it is not implemented. All 
OS/4 keyword spellings are accepted as alternates by the OS/3 DTFPT declarative macro. 
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17. 6. a: “Compan bility with the. .9200/ sre Series 


All 9200/9300 Series DTFPT keywords, as documented in the operating ‘system locs 
programmer reference, UP-7526 (current version), are accepted by the OS/3 DTFPT 
declarative macro. Of these, the mellewying are accepted but not aun the 
remainder are implemented: 


ATIN 
CHNL 
DEVA 
FIGS 
LTRS 


Moreover, you should note that the 9200/9300 Series letter/figure shifting capability is 
not supported for input files by OS/3. To run 9200/9300 Series paper tape programs that 
process -input files with. shifted characters, you should remove the FIGS: and LTRS 
keywords from the DTFPT declarative macro call, substituting the FTRANS, LTRANS, and 
SCAN: keyword parameters and providing the necessary ngures and nes translation tables 
and scan table elsewhere in ual program. ar 2 


Another point ‘af differents is maximum block size. OS/3 allows 4095 bytes; the 
9200/9300 Series allows only 256. Paper tape files created under the 9200/9300 paper 
tape data management system may be processed under OS/3; whether these should be 
restructured, or existing programs modified to exploit'OS/3’s 4095-byte maximum block 
size, are matters of judging: ‘the’ trade- offs between ~ increased Eperaseee and the 
programming effort involved.’ 


A fourth Aoi of ditferanes is that 0S/3 ee no combined paper tape file. LEA GRBILY: To 
punch a paper tape and then read the tape for error checking in OS/3, you should code 
two DTFPT declarative macros (one for input processing, one for output, using different file 
names) and should specify two separate job control DVC-LFD device assignment sets (one 
for Bach aa 


17. 6. 3. Compatibility with IBM Systern/360 Dos 


The OS/3 DTFPT declarative: macro accepts all System/360 DTFPT pie parameters 
documented in /BM Systems Reference Library: DOS Supervisor and |/O Macros, Twelfth 
Edition (February 1972), Order No. GC24-5037-11. Of these keywords, the following are 
accepted but not implemented in OS/3: _ 


DELCHAR 
DEVADDR > 
DEVICE” 

_ ERROPT © 
-MODNAME 
SEPASM 
WLRERR 
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A second point of difference is maximum block size. IBM System/360 DOS provides 
32,767 bytes; OS/3 allows 4095. Paper tape files containing fixed, unblocked records 
larger than 4095 bytes, or undefined records larger than 4094 bytes, must be restructured 
to be processed in OS/3, and existing programs exploiting the larger IBM maximum block 
size must be modified. 


A third point of difference is that, unlike IBM System/360 DOS, OS/3 paper tape data 
management does not provide for skipping over strings of consecutive end-of-record stop 
characters without intervening data when processing input files containing undefined 
records. 
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Appendix A. Functional Characteristics 
of Peripheral Devices 


The tables in this appendix summarize the functional characteristics of the peripheral 
hardware available in the SPERRY UNIVAC Series 90 Data Processing eas that are 
relevant to OS/3 data management usage. . 
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Table A—1. SPERRY UNIVAC Card Reader Subsystems Characteristics (Part 1 of 2) 


0717 Card Reader Subsystem 


Characteristic ea oe Description 








.. Card otientation a 
- (80-, 66-, and 51-column cards) 


Read technique 


Face in, with column 1 leading, and row 9 down 







Dual redundant, solar cell technique using photo transistors, 
Column 0 amplifier checking 





Read modes 





Image mode: 160 six-bit characters per card 
Translate mode: 80 characters per card 
‘Available ‘code: 8-bit EBCDIC . 














Read station sensing Column by column. 






Stacker capacity 2000 cards 
0716 Card Reader Subsystem 


Card orientation 
(80-, 66-, and 51-column cards) 


Read technique 






Face in, with column 1 Jeading and row 9 down 








Dual redundant, solar cell technique 
using photo transistors. 
Cojiumn 0 amplifier checking 











Read modes image mode — 160 six-bit characters per card 










Translate mode — 80 characters per card 


Three available codes: 





a 8-bit ASCII 
a 8-bit EBCDIC (required) 
a Compressed code 












Read station sensing Column by column 










Hopper capacity 2400 cards 






Stacker capacity 
Normal (stacker 2) 2000 cards 
Reject (stacker 1) 2000 cards 


0719 Card Reader Subsystem 


Card orientation 
(80-, 66-, and 51-column cards) 


Read technique 














Face down, column 1 to left and row 9 
facing away 












Two columns of photosensitive sensors and 
light-emitting diodes 

Dual redundant. 

Column amplifier checking 








Hopper capacity 2400 cards 
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Table A—1. SPERRY UNIVAC Card Reader Subsystems Characteristics (Part 2 of 2) 


0719 Card Reader Subeveien 7 


Characteristic ae __ Description, : : as 

| Read.modes Image mode: 160 six-bit characters per card 

Translate “ode; 80 characters per card 
Read station sensing ~ Column by column : Vee 

4 Hopper capacity 1000 cards 


Stacker capacity 4 000 cards 
Normal : 3 
Reject 





Table A—2. SPERRY UNIVAC Card Punch Subsystems Characteristics (Part 1 of 2) 


3 ’ 0605 Card Punch Subsystem 
oe ; '~ Characteristic ~~: padre “<< -- Description - 
80-column cards 


~ Punch mode 2-column serial 


at Check mode ~ Punch motion check 


Punch rate 75 cpm (full card) ei oor | 
160 cpm (28 columns only) — ae a 
Input capacity 700 cards 2 gf : 


Output capacity * | °700 cards (primary stacker) 
100 cards (reject stacker) 


Punch translation 
image mode 160 six-bit characters per card 
Translate mode : ‘| 80 characters per card’ ~ 
Available code: EBCDIC 


fm, 


0604 Card Punch Subsystem — 


' Check mode _ | Read of punched data 


input hopper capacity . WOOcards ne eS ere 
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Table A-2, SPERRY UNIVAC Card Punch Subsystems Characteristics (Part 2 of 2) 


0604 Card Punch Subsystem 


"Output stacker capacity 1000 cards (normal and select stacker) _ 


Punch translation 
' Image mode — : 160 six-bit characters per card 
Compressed mode 80 characters per card 





Table A—3. SPERRY UNIVAC Printer Subsystems Characteristics (Part 1 of 5) 


0773 Printer Subsystem 


110 to 680 ian: depending on character contingencies: . 


Available character sets 





















Print speed 








Characters sets per band 





Nominal print rate (Ipm) 













48-character business 500 










63-character.print 400 
48/16-character print . 400/670 | 
85-character print (plus 1 character) 310 





128-character special 217 
96/(16-16)-character 
ASCII 


256-character special 














217/500 
114 


































Line advance 
timing 


8.75 ms for spacing 
first line; for 
skipping each 
subsequent line: 
3.33 ms at 6 Ipi 
2.50 ms at 8 Ipi 


8.75 ms for spacing 
first line; for 
skipping each 
subsequent line: 
2.22 ms at 6 Ipi 
1.67 ms at 8 Ipi 


8.75 ms for spacing 
first line; for 
skipping each 
subsequent line: 
1.67 ms at 6 Ipi 
1.25 ms at 8 Ipi - 













120 print positions (columns) by standard printer; 132 or 144 columns 
by feature 


Number of print 
positions 














Form advance Vertical format buffer 


control 










Line advance 
rate 


Single space only, 22 inches/second 


3 to 18.75 inches wide 
1 to 24 inches long 


Form dimensions 













Standard 48-character set. Any number of characters, up to 256, with 
options, 


Horizontal spacing 10 characters per inch 


Vertical spacing 6 or 8 lines per inch, operator-selectable 





Character set 






. 
. 
. 

. 
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Table A—3.. SPERRY UNIVAC Printer Subsystems Characteristics (Part 2 of 5) 


0770 Printer Subsystem 
Printspeed 0770—00 ‘0770—02 . 0770-045 —> 


112 to 1435 Ipm, ..213 to 2320 Ipm, ~:~ | 337 to 3000 Ipm, 
depending on character depending on character : depending on character 
contingencies ere: : * contingencies 


112 Ipm — 384 contiguous 213 Ipm.— 384 a la 337 Ipm — 384 contiguous 
characters characters ~ characters - 


800 Ipm — 48 contiguous - 1400 Ipm — 48 contiguous - 2000 Ipm — 48. pepeauous 
characters zo characters characters 


1435 Ipm — 24 contiguous 2320 Ipm — 24 contiguous .. 3000 Ipm — 24 contiguous: 


characters ~ characters characters 


Line advance timing Advance and print i Serene tans a 


1 line 120.0 a a - 118.0: 
2 lines 127.6 ‘ - s- |» 123.7 
3 lines - . 135.2 129.4 
n+1 line 120+7.6n : 118+5.7n 


Number of print positions Full print width of 132 print positions placed anywhere ona 16.5- 
inch form. With 22-inch form, only central 13.2-inch portion can be. 
used (160 print positions with feature). 


Form dimensions Continuous forms with standard edge sprocket-holes from 4 to 22 inches 
in width. Carbons may be attached or unattached with multicopy forms to 
a maximum of six parts. Recommended pack thickness not to exceed .0155 
inch for high quality print. 


Character set Standard 48-character set. Any number of characters up to 384 with 
options. 


Horizontal spacing 10 characters per inch 
Vertical spacing 6 or 8 lines per inch, as determined by program 
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Table’-A—3. SPERRY UNIVAC.-Printer.Subsystems:.Characteristics (Part: 3 of:5) 


Characteristic 


Print speed 


Line advance 
timing 


Number of print positions 


‘| Form advance control ~~: 


Line advance: rate*.*: 
“Form diniensions 
Character set ~ 


Horizontal spacing 


| Vertical spacing 





0768.Printer:Subsystem 
Description 
0768—00 - . 0768-02 =. 0768—99 
* 900 through 1100 Ipm'*). ff: 840 through 2000 Ipm © 1200 through 1600 Ipm 
11,5 +5.1 (n—1) ms — 6Jines:per inch 
11.5+5.7 (n—1) ms — 8 lines per inch 
’ . where: n = number of lines advanced 
132 character print positions including spaces 
« Mertical format buffer and loop:control; up to 132 lines per command: 
“25 ips 
4.to.22.inches wide ... -. - . - 
__ 1 to 22iinches long 
~0768—00 63 characters ~~ 
-0768—02 94 characters 
' 0768-99 132 characters 
10 characters per inch 
6 to 8 lines per inch Be a ger aS Sane ee _ 
3 f sey 
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er Table A—3. SPERRY UNIVAC Printer Subsystems Characteristics (Part 4 of 5) 
hakcig Me sactet cies Seas a3 _ 0776 Printer Subsystem 
Print speed. ; Available... . Character... J... -.Nominal naiier rate Hains. ue moss 
ut .| Character .|.. sets per | — Z 
- sets -|... band . ., 0776-00, 01 - 0776-02 ma 
1 
ve 
3 
4 
6 
8 
1 
1 
*For duty cycle reasons, maximum speed 
in Ipm is limited by a minimum time 
between consecutive line feeds: 55 ms 
for the 0776— 00, 01, and 48 ms for the 
0776-02, 03." , 
: Time in ms 
darker BES potas Advance and_print 
Line advance timing 
1 line 16 14.2 
¢ 2 lines 23.6 19.9 
4 3 lines . 31.2 ae 
= 4 lines i 38.8 | 31.3 
"5 tines SESS BGR OS OP? aa * 
“ nttilines) o~  * T6+7. Ga” “*44°24+5.7n 
Number. of print positions. © | .:136 print ssectiichoinelldiid pet 
Form advance control. — “\ 2 Mertical format buffer ~ 
Line advance rate 22 inches/second 
Form dimensions , “4 to 18:75 inches wide 
ae we a eh ee 1 to 24 inches long 
" “Character set | Standard 48-character set. Any n number of characters up ae 
384 with options. 
10 characters per inch 
Gor 8 linés per inch, as determined by program 
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Table A—3. SPERRY UNIVAC Printer Subsystems Characteristics (Part 5 of 5) | 


ti a ~ 0778 Printer Subsystem 
Characteristic” ~ oo ie OY ae ; ee es “Description 


Print speed “| 240 to 560 Ipm, depending on character contingencies, at 6 lines per inch (Ipi) 
; et ' 1 °(2.36 lines per cm), and single line spacing. 


1 ‘Available character sets Nominal print rate (lpm) 


Basic _ Speed Upgrade 
00/01 02/03 


48-character business _ 300: 510 


64-character sein bP 240 - 415 
48/16-cheracter print 240/255 415/560 
oi 128-character print 120 240 
~~ | 335-character print* 
tnegqrareesiira | Mme | stnzse em | etn 18 em 
| single ms | 


double 





triple : Ze 


Number of print positions} 120 print positions (columns) per line; 136 columns by feature. 


Number of characters ___| Standard 48- or 64-character set, with five. sets on a.240-character 
band; or up to 256 characters with expanded character set. control feature; 
48-character set band repeats five times resulting in 240 characters; 
64-character set band repeats four times resulting in 256 characters. : 


Vertical format buffer ee ae 

Single space only, 22 inches (55.88 cm) per second (slew rate), 
Ribbon feed __ Bidirectional, self-reversing; ribbon ferdoval wnehouit rewinding 

[riienne fees or plastic film | 

EBCDIC, ASCII, or any 8-bit code 


Form dimensions 


























Continuous -single- part. and. multipart. (up. to six parts or Fup 

to 0.018 inch (0.457 mm) thick) with standard edge sprocket holes. Printer” 

can also accept continuously sprocketed, 1-part card stock forms of | 

weights typically used for punch cards, postcards, or offset masters. Form 

widths from 4.0 inches (101.60 mm) to 18.75 inches (476.2 mm) and lengths 

up to 24 inches (609.6 mm) can be accommodated. Forms longer than 17 inches 
(431.8 mm) can be run with casework door open, but noise level increases with 
door open. 


Horizontal spacing 10 charcters per inch (2.54 mm per print position) 
Vertical spacing 6 Ipi (4.23 mm per line) or 8 Ipi (3.17 mm per line), 
operator-selectable. 


*The ‘'16" array is commonly a numeric subset. Extra 16 arrays are included in the 96/16—16 arrangement to 
make up a total number of 256 characters in a band. 





Table A—4. SPERRY UNIVAC Disk Subsystems Characteristics 


8424. «fe 8425 - 8430 »«. 8433 
Disk Subsystem. Disk. Subsystem Disk Subsystem ~~ Disk Subsystem 1, 
58.35 million | ys | 58.35 million _, 100 million : 200 million 
DACA pd cas AB | 1 to 8 {with optional. .|- 1 to 8 (with optional 
; feature up to 16) feature up to 16) 


2400 rpm -|° 2400 rpm 3600 rpm |] 3600 rpm 


Description 
8418 


8413 8414 - 8415, 8416 
Diskette Subsystem {| _ Disk Subsystem -Disk ‘Subsystem Disk Subsystem Disk Subsystem 


Characteristic 
a ee 8411 
nalts Disk Subsystem i 
242,944 bytes (using 29.17 million 33.1 million per track | 28.95 million 28.9 million or 
tracks 1—73 for data)” : i ine ; : : : ~ 57.9 million 


‘Data capacity (8-bit bytes) 7.25 million 
Number of disk units 


i | 5oMHz | 5.0 MHz _. | 2.5 MHz 2.5 MHz 6.45 MHz 6.45 MHz 


192 tracks per inch : 370 tracks per inch 
13,030. : 


. som 
“| Bit density 1100 ppi ‘ 3268 ppi ; 2 4040 fixed = 4040 pulses _ 4040 ppi 
: : a 4040 removable per inch {ppi) : 


Track density 100 tracks per inch 48 track per inch 200 tracks per inch 370 fixed 192 tracks per inch 370 tracks per inch 
(free format) . 185 removable : : ode : 
3,328 bytes per track | 7294 . - | 10,240* froze 10,240. fp. 7294 


400 tracks per inch 


Track capacity (byte) 3625 . 


“py A8YH 8908-d/N 


Number of tracks . 200 + 3 spare 
usable tracks per 


disc surface 


Number of surfaces per 
disk unit 


Positioning time (seek time) 


77 total, 73 for data 
use per disc surface 


.200.+.3 spare 
usable tracks per 
disc surface 


808+7 Spare tracks 
404+-4 spare tracks 


Data 3 
Positioning 1 fixed 
Data 2 removable 


404 + 7 spare -.- - 


uSable tracks per 
dise surface 


Data 7 
Positioning 1 


"404 or 808-+7 spare 
usable tracks per 
disc surface 


400.+ 6 spare — 
usable tracks per 
surface 


Data 7 
Positioning 1 


400 tracks per inch 


400 + 6 spare 
usable tracks per 
surface 


404 + 7 spare 
usable; tracks per 
disc surface 


808 + 7 spare 
tracks per disc 
surface 


~ LNAWSSVNVW VLVO oISVa 


fis 


€/SO OVAINN. AYYAadS 


Minimum | ae 
Average 83.33 ms 
Maximum ate 

156 kilobytes per 128 bytes in < 6ms 
second . . 


628 kilobytes per 
second: : 


312 kilobytes per 
second 


625 kilobytes per 
second 


625 kilobytes per 
second 


312 kilobytes per’ 


312 kilobytes per 806 kilobytes ‘per 
second 7 


r 806 kilobytes per 
second - second= ~~ aia “7 


~ second 





Characteristic 


bee enc eee free 
Data transfer rate (maximum) 68,320 frames per second 


Tape speed 42 7 inches per second 


Tape direction 
Reading 
Writing 


Tape length (maximum) .. | 2400 ft a 4 oi 


Tape thickness 


Forward or backward 
Forward 


Maximum block. 
size (bytes) 


Minimum 
block size 
(bytes) 


18 


Interblo: 


4 


cuon . 
Interblock gap time ay _ 
Nonstop 


Start-stop 


17.6 ms 
23.6 ms 


14.1 ms 
20.1 ms 


Pulse density — 


Recording mode 


Reversal time... 
Rewind ‘time 


Simultaneous operation Optional 








Table A—5. UNISERVO Subsystems Characteristics 


a 
a 


Forward or backward 
Forward 


v A284 8908-dN 


Forward or backward 
Forward 


Forward or backward 
Forward 


Forward or backward 
Forward 


Forward or backward 
Forward 


oe ee : | ‘ 

65,535 
3 on a) 
nfo 2) m 
Zz 
a 
| prac “track oS 
Q-track 7-track- ie “b_9-track” 7-track 9-track >> 
Pesn, [orm [osn. | BS 
- * * ae: fae « - oe comers food oO Hf 
pf | ..14.1 ms = CS 
me: 

° Phase 

encoded 

Optional _ mi 

me 
(e) 





a, 
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( Table A—6. SPERRY UNIVAC 0920 Paper Tape Subsystem Characteristics 


Reader mounting Mounted on a 7- by 9-inch panel having a pin spindle 
for handling reels containing up to 50 feet of tape 
(for tape reader without an optional spooler) 


Unidirectional (right to left) 


Tape channel capacity Capable of reading 11/16-inch, 7/8-inch, or 1-inch 
paper tape; 3-position tape guide available to adjust 
to tape width used 


Read speed 300 characters per second at 10 characters per inch 
Type of tape All conventional perforated tapes with a light 
transmissivity of 40% or less 


Stop and start capacities Can stop on character or before next character; on start, 
unit reaches full speed within two characters 


Tape spooler Up to 5-inch reels can be used with the spooler to allow 
reeling of approximately 300 feet of paper tape 

Tape leader Approximately 3 feet of tape leader required when spooler 
mechanism is used 


Tape trailer A 12-inch trailer must be provided to prevent false broken 
ime, tape indication 


Tape channel capacity Handles paper tape width of 11/16 inch or 1 inch; five 
levels of tape characters with 11/16-inch paper tape 
being used; or 5, 6, 7, or 8 levels of tape characters 
with 1-inch paper tape in use. Tape guide adjusts to 
conform to paper tape width. 


Punch speed 110 characters per second at 10 characters per inch 


Type of tape Oil base paper tape is provided. A compatible tape 
utilizing a paper-plastic-paper sandwich is also 
available. 


Stop and start capabilities Punching is performed one character at a time. Tape 
punch is capable of stopping and starting between 
characters, 


Tape feeding The tape punch handles a paper tape reel of 1000 
feet with sensing signals to indicate low paper 
tape supply. 
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‘Appendix B. Error and Exception Handling 


B.1. GENERAL 


All programs using the services of OS/3 data management execute imperative 
macroinstructions to obtain specific processing. OS/3 data management performs part of 
the desired data manipulation itself, but frequently calls on other OS/3 system programs 
(such as the physical 1OCS or disk space management) to perform other parts of the task. 

Most of the time, the desired service is performed exactly as’ requested, and control is 
returned to you inline with no need to issue messages to the system console or to the log. 

Sometimes, however, errors or exceptions to desired: performance occur; these may be 
detected by data management’ or the’ other system programs at various points in 
processing. -_ 


OS/3 data management is responsible for noting all errors and exceptions reported to it by 
the other system programs, as well as for testing, within itself, for other types of error or 
exceptions. When any such condition is detected, OS/3 data management will always: . 


- make appropriate entries in certain fields of the DTF file table, which your program 
"may address in order to learn of exceptions and errors and take the proper course of 
action when control returns to you; 


= log and display messages that call for operator intervention or are helpful in after-the- 
fact tracing of your program ‘s action; z 


= branch to an error/exception routine in your program. 


B.2. RETURN OF CONTROL 


The design policy of OS/3 data management is never to terminate a user program. This 
means that data management will always return control to you after detecting an error or 
exception. If you provide the address of an error/exception routine in your DTF 
macroinstruction, data management returns control to this address for all conditions of 
error or exception. If you do not provide this address, data management returns control to t 
you inline, at the next sequential instruction after the macro call. Retries by PIOCS have 
already been performed at this point in the processing. 
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B.2.1. Error Handling with ISAM 


When OS/3 ISAM detects certain logical errors, the processor sets a bit in the DTFIS table 
that prohibits. further reference to the file, other. than to: ‘Close it. These. logical errors (also 
listed’ in’ Table B—3) are: 


# Invalid macro sequence 
a Invalid ID 
L Invalid index search 


u =€§©6 File space exhausted 


ise 


B.3. SYSTEM ERROR MESSAGES =e 


In 0S/3, “system error. messages. are contained - ina general file, of. ‘canned “messages, 
which are: listed or. displayed under the control of the OS/3 supervisor. When OS/ 3 data 
management detects. a loggable error, it acts through a logging transient routine to provide. 
the supervisor with, ‘the proper. code for the specific message to be logged, which. the 
transient translates from an error code field in the DTF file. table. This internal error code. 
may. also be accessed by your program; it is. placed. in byte 56 of. the DTF. file table by data 
management. | 


a 


B.3.1, Data Management Error Messages 


The error messages issued by OS/3 data management are shown in Table B—1, the first 
column of which lists the internal error code placed in byte 56 of every DIF file table 
(filenameE): When these messages are printed or displayed, they will include, ‘between the 
message number and the text, the 7-byte logical filename (LFD. name) and the channel and 
device address which are maintained in the physical unit block (PUB) on which the file in 
question is assigned. Table B—1 also provides for each message an explanation of the 
probable cause of the error, a notation as to the data management module which issues it, 

and suggested actions by which you may recover from the error. Note, error messages 
relating to unit record also apply to the 8413 diskette. 


t 


. Internal | 
Hexadecimal , 
Code 


DM 01 | 


DM 02, =. 


DM 03 
DM 04 | 
DMO05. 
DM06. _ 
DM 07 
DM 08. 
DM09._. 
DM 10... 
DM.11 
DM 12. 
DM 13 | 
DM 14 | 
DM 15 


DM 16 


FCB NOT FOUND/INVALID 


, 1/0 ERROR DETECTED WHILE ACCESSING VTOC 


. FILE SERIAL NUMBER ERROR R*C° 


PREFORMAT WRITE ERROR DETECTED 


_ INVALID IMPERATIVE MACRO/MACRO SEQUENCE ISSUED 


Table B—1. .OS/3 Data Management Error Messages (Part 1 of 6) 


z 


‘Message Number and Text 


OPEN ISSUED TO OPENED FILE 


filename REQUIRES channel/device vsn WITH RING R C 


filename REQUIRES channel/device vsn with {Ne au R*C 


BKNO 


FORMAT-1 LABEL NOT FOUND 


VOLUME SEQUENCE ERROR RIC 


_ CREATION. DATE ERROR RIC. 


- SPECIFIED NON-EXTENDABLE | 


FILE SECURIT-Y CHECK RIC. 


. ATTEMPTED.ACCESS. TO AN UNOPENED FILE 


INVALID DTF, TyPE=nn@ 


PARTITION INVALID FOR SPECIFIED DTF, TYPE=nn @ 


Issuing Module 


OPEN 
--SAM tape 


__ OPEN/CLOSE 


SAM tape. 


OPEN/CLOSE 


OPEN/CLOSE 


OPEN 


_ OPEN 


OPEN 


. OPEN/EXTEND 


OPEN 
OPEN, 


All DMS 


. All DMS 


OPEN/CLOSE 


OPEN 


‘Suggested Action 


5 : 


C (See note.) 


Tr 


-C (See note.) 


_O (See note.) 


T, C, (See note.) 
T,C (See note.) 


T,M 


TC 


H (See note.) 
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€-d ~ 


Internal 
Hexadecimal 
Code 


Table B—1. OS/3 Data Management Error Messages (Part 2 of 6) 


Message Number and Text 


INVALID BLOCK SIZE SPECIFIED 


RECORD SIZE INVALID 


INVALID DEVICE CHARACTERISTICS SPECIFIED. _ 


NO BKNO SUPPORT.IN SUPERVISOR 


- INVALID OR MISSING DEVICE ASSIGNMENT OR DEVICE NOT AVAILABLE 


. HARDWARE ERROR — CHECK ERROR STATUS/SENSE BYTES 


UNRECOVERABLE 1/O ERROR DETECTED | 


_ INVALID REQUEST.(ID) — EXCEEDS FILE LIMITS GETCS ERROR: — 


. WRONG LENGTH ERROR DETECTED... 


DATA CHECK DETECTED 


. READ ERROR ON RUNLIB DEVICE OR SPOOL FILE 


PUNCH DOES NOT HAVE READ. FEATURE 


NO HARDWARE FOR STUB READ 


. VALIDITY CHECK ERROR 


(No console message appears, but this code in the... 
DTF means: record not found. for random function.) 


RECORD NOT FOUND FOR SEQUENTIAL FUNCTION 


INVALID FUNCTION ISSUED FOR OPTIONAL FILE 


(No console message appears, but this code 


in the DTF means: end of data detected for . 
sequential operation.) 





Issuing Module Suggested Action 


OPEN/SAM/NI 
UNIT RECORD 


ISAM/SAM/NI H,or T,D 
UNIT RECORD 


OPEN 

SAM tape 

UNIT RECORD 

All DMS 

All DMS. 

Disc. DMS 

Disk DMS, SAM tape 
Disc DMS 

OPEN 

UNIT RECORD 
UNIT RECORD : 
UNIT RECORD 

Disc DMS 


SAM/NI/ISAM/ 
IRAM/MIRAM 


ft. 


Disc DMS. T,L,C 


Disc DMS 


LINAWSDVNVW VLVG 2ISVE | 
€/SO DVAINN AYYadS 





v “A8YH 8908-dN 


b-d 


Internal 
Hexadecimal 


35 
36 
37 
38 
39 
40 
41 
42 


43 
45 


47 


48 


50 
51 


52 


53 


Code 


Table B—1.° OS/3 ‘Data Management Error Messages (Part 3 of 6) 


_ Message Number and Text 


ADD OF RECORDS RESTRICTED BY PREVIOUS OPERATION 


DUPLICATE RECORD—REJECTED 


SEQUENCE ERROR — RECORD REJECTED 


‘END OF DATA RETURNED BY SYSTEM—ILLOGICAL 


CONDITION : ere 
INVALID FILE CONDITION — INDEX INVALID 


INDEX SPACE WILL NOT SUPPORT PRIME DATA 


FILE SPACE EXHAUSTED 


CHARACTER MISMATCH 


‘INVALID CONTROL: CHARACTER 


LINE TRUNCATED 


EXTENT TABLE EXHAUSTED — 


filename channel/device vsn. DATA’ BLKS: READ = nnnnnn-EQOV = nnnnnn IC 
ERROR DURING LABEL PROCESSING 

KEY LENGTH/LACE FACTOR INVALID 

PROCESSING INHIBITED BY ERROR CONDITION 

RECSIZE REGISTER NOT SPECIFIED FOR UNDEF FORMAT 


INVALID SUBFILE NUMBER SPECIFIED 


~ NO SPACE AVAILABLE FOR SUBFILE ENTRIES 


HARDWARE ERROR DURING FILE CONTROL BLOCK 


UPDATE 


INVALID JCL SPECIFIED OR INVALID USE OR NAME INVFB 
OR LCB JOB CONTROL STATEMENT INVALID USE OR NAME ~ 
IN VCB OR LCB STATEMENT FOR printer file 


_ SAM tape 
“UNIT RECORD 





bv A8Y 8908-dN 


Issuing Module , Suggested Action 


ISAM add 
ISAM add 
ISAM load 


ISAM 


ISAM add and retrieve 


ISAM SETFL. 
ISAM, SAM tape — 
Printer 

Printer 


Printer 


ANSWSDVNVW Vivd oIsva 
€/SO SVAINN: AdYadS 


Disc OPEN/EXTND 
UNIT RECORD 


SAM tape: 
SAM/DAM/NI ~ 
OPEN disc 
ISAM 

SAM tape 


NI 


$-d 


NI 


All disc | 





etude 


7 Table BET. “08/3 Data Management Error Messages (Part 4 of 6) — 










Internal 
’ Hexadecimal — 
Code * 















‘Message Number and Text issuing Module Suggested Action 


STD SYSTEM/USER LABEL NOT FOUND SAM tape 
ce ne eae UNIT RECORD 




















DM56  . -FILENOT FOUND | SAM tape 





SAM tape, Disc DMS 


DM57_ . WRITE ATTEMPTED ON UNEXPIRED FILE RIC 
-_ . UNIT RECORD 





DM58 .° “FSN DOES NOT MATCH FIRST VOLUME VSN ~ SAM tape 


DM59 © STD LABEL FIELDS DO'NOT MATCH JCL SPECS ‘SAM tape 








DM 60° © TAPEMARK: NOT FOUND AT FILE BOUNDARY SAM tape 





-AILDMS 





DM 61 INVALID DTF FIELD: PARAMETER, OR PARAMETER 
COMBINATION, TYPE=nn © 




















DM 62° °’' '°80 COLUMN CARDS READ WITH BLOCK SIZE 81-96 “UNIT RECORD 





DM 63’ © “OPEN ERROR: BINARY MODE CARD INPUT UNIT RECORD 


FILE CANNOT BE SPOOLED IN 















DM 64 COMBINED CARD FILE CAN'T BE SPOOLED IN UNIT RECORD 





DM65 _—sILLEGAL KEY CHANGE DURING UPDATE MIRAM 


















DM 80 BEGIN OUTPUT FILE PUNCH RECOVERY. R,U? _Read/Punch _ 
DM 81 | PERFORM PUNCH RECOVERY STEP 2A. R,U? Read/Punch 
DM'82.-—« PERFORM PUNCH RECOVERY STEP 2B. R,U? Read/Punch 
DM'83. “BEGIN OF FILE MARKER NOT COMPLETE.**1,C "CAI papertane 


is 





DM 84 —_—sISIT’ END OF FILE OR END OF TAPE. **F,T ~~” All paper tape 
DM85 INSUFFICIENT SPACE ALLOCATED FOR PRINTER SKIP CODES . Printer 
DM86 . SPOOL FILE FOR CARD READER FILE WAS NOT CREATED _ UNIT RECORD 





DM87 _ | UNRECOVERABLE ERROR WHILE LOADING THE VERTICAL. _ Printer ..... 


FORMAT BUFFER OR LOAD CODE BUFFER. 






DM88 jobname WAITING FOR LOCK Ibl-filename” FILE LOCK 





DM89 DISKETTE DRIVE NOT AVAILABLE UNIT RECORD 





_INSWSSVNVW VLVd olsva 
£/SO-DVAINN AduadS 


bA8Y 8908-d/N 


ogg, 


Internal 
Hexadecimal 
Code 


NOTE: 


f ‘ 


Table B—1. OS/3 Data Management Error Messages (Part 5 of 6) 


Message Number and Text 


BEGIN ERROR RECOVERY ERROR CARD. R,U? 

HAVE BLANK CDS BEEN PLACED IN HOPPER? R,U? 

DO RECVRY STEP 2. REFILE LAST (2) CD(S)? R,U? g 
PERFORM PUNCH RECOVERY STEP 3.R,U? 

PREPUNCHED CARD DETECTED DURING ERROR RECOVERY 
PUNCH OFF-LINE.R,U? 


PUNCH MISFEED. R,U? 
LOGICAL END OF FILE REACHED Al* 

ILLEGAL EXTEND, STANDARD LABEL NOT SPECIFIED 
ILLEGAL EXTEND, HDR2 NOT FOUND 

ILLEGAL EXTEND, EOF1 OR EOV2 NOT FOUND 
ILLEGAL EXTEND, RECFORM INVALID < 
ILLEGAL EXTEND, RECSIZE INVALID 

ILLEGAL EXTEND, BLKSIZE INVALID 


ILLEGAL EXTEND, FILE FOLLOWS THE FILE TO BE EXTENDED 


Operators choose one of the following action messages to reply to data management error messages. 


Qco-z 


Retry after mounting correct volume. 


Ignore the error condition. 


Cancel job. 


Unrecoverable; user error routine required. 


nn is a message type subcode that is used to provide daditionél information as to why the associated message was displayed or printed. 


Refer to Table B—1A for the subcodes and their explanations. 


Issuing Module 


Read/Punch 
Read/Punch 
Read/Punch 
Read/Punch 


Read/Punch 


Read/Punch 


*: Read/Punch 


Tape extend 


- Tape extend 


Tape extend 


. _ Tape extend 


= Tape extend 


Tape extend 


- Tape extend 


Tape extend 


Suggested Action 





* LNSWADVNVWVWEV" SISv 
€/SO OVAINM AuHadS 
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Table B—1. OS/3 Data Management Error Messages (Part 6 of 6) 


i 


LEGEND: 


Suggested actions 


B. Check your data and rerun the job. 

Ci. Control stream content should be checked. 

D. Checking of program dump is recommended i 

H. Program should handle this occurrence, proceeding or otherwise as Se sapanined: 


L. Program logic should be checked. 


M. Maintenance check of disk pack check. 


O. Operator intervention is needed. See system messages operator/programmer reference, UP-8076 (current version). 
R. Reorganize file, getting more space or rebuilding index by new load. ; =f s . le . 
ae a = ae é _ 
a eee 
S. Program specifications to data management should be checked. 
L Program termination is recommended. * 


V. VTOC should be printed out for check. 
W. Warning message. 


Y. » Rerun when device is available. . 
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Table B—1A. Data Management Error-Message Subcodes (Part 1 of 2)° 


‘Associated Data Message 
' Management Type HPs Explanation 
_ Error Message Subcode*® ° 
Invalid DTF address’ 
Invalid DTF partition control appendage: (PCA) 
Invalid DTF partition control appendage (PCA) address 
File type: ‘code in DIF does ‘not maten type. ‘code in .lOCS processor. 
Wrong key location 
Invalid DTF address in:partition control appendage (PCA) 
Missing extent table entry for partition control ‘appendage (PCA) mS 
Single mount specification: does not match ‘specification used to create file. 
-Singlé mount specifications do not match between Format 2 label and DTF 
| Variable record specifications do not match between Format 2 label and DTF 
Two 1/0 areas are lass eee : 
Index buffer not contiguous \ with YO: area 1. 
1/O area 2 edares? not contiguous -ivith \/O area 1 address. 
Index buffer not contiguous ae 1/0 area 4 aes: 


Index ree intended, but ‘no index buffer or key argument specification 


Seek address not specified ae ote 


Key argument r not speeitied 


Index bute not specified 


Key-location does. not match specification used to create file. 


Key ‘location values do not! match between Format 2 label and DTF 
Key location value less than’'4 with variable file 

Key specications not zero eeretee last vali d key entry | 

Key flag values de bi aa seen Scie 2 label and DTF. 
Key size does not equal original. keysize used to create. file. 
Nonindexed output intended to an indexed file 

| ndexed. access intended to a ponindexea file 

No work aréa or vo register ‘specification 


: vo cceieee ecial incorrectly; 


Work area and 1/0 register specified together 
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Table B—1A. Data. Management Error: Message.Subcodes (Part 2 of 2) © 


‘Associated Data Message ie 
- Management Type gif ag Explanation 
Error Message | Subcode* 
-DM61 (cont) Double buffering with update or random:mode. ~ 
Double buffering with input and add. »- 
Double buffering: saith sdexed input 


Variable. build: ragletee sanecities snGortectlyi 
Farward-direction not, Penesitied with output file 
STD labels not specified with ASCII file “es 
aNnEH ep seacitving: ASCII BLKSIZE: ‘not greater :than:9999 : 
| BKNO=YES_ no not specified awit, black numbered jane: 


The. reader does not-have: the, 96-column read. feature. 


4, Block. size. and overflow. percentage are too large for disk with low number of 
Se coos Dees eee ae 


- 


UFonast other ae fixed ae ons variable unblocked 
\/O area 2 not specified ath Sombinied file 

Extend not allowed with ‘combined file 

“Multisector | VO invalid with combined efile 


Block ee record size “equal zero --~ 


An address in the DTF is not within the bounds of the user program 


Invalid DTF, CR type not se al when Format 2 label active in multivolume 


User specified seek address j is “not ord: aligned « or 1/0 area’s are not half-word 
aligned aed pec ran or 





“When error condition Occurs, the related Stibeoda (in hexadecimal) i : placed in byte 44 of the DTF file table. 


tet pbs 


saabet ene. tei fret 


B. 3. 2. Disk Space Menedomens Error Codés ° 


The disk space management routines of the 0S/3. supervisor ‘do not generate error 
messages, but instead load a hexadecimal érror*code into general register O for the error 
or exception conditions listed in Table B-2. The first. column of this table contains the 
hexadecimal error code, which is loaded by disk space management into register O, byte 3. 
This is followed by an interpretation of the error: or exception: condition and suggestions for 
fecovely action. 





ga. ORY SG hy 
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Table B—2. OS/3 Disk Space Management:Efrof’Codés SO 


: ‘ctccnak =: eas Sahin dee Sige Gite ties, 2 Peg e eae Sh ye tace wth aes By ARES ae. ae OS “ Sageesed #3 
Hexadecimal Interpretation Recovery 
Code Action 


eee an) 
as a oo Tees 


Unrecoverable hardware !/O error on WRITE command; _ List and examine VTOC, 
wTOC may be disturbed.» using OBTAIN macro. Attempt 


Hous Lakac .. 4) “fo copy all files to’ another disc; 
Unrecoverable fciawer 1/0 error on READ coienianial then reprep the suspected Gefective 
VTOC is disturbed. disc. 


Unrecoverable hardware |/O error on READ command; ~ ci ees. 4, Same as error code 31, 
VTOC not disturbed. wabont od ae 


Indicated device (PUB) either not allocated or nonexistent... : .. ...,: Check the VOL_job control statement 
: : ~ and'the volume sequence number 
of the disc volume. 


of 


File 1D error: 


a For EXTEND, SCRTCH, RENAME, OBTAIN: the. format 1 ioe List VTOC and check, all 
record cannot be found on specified volume. ~ ‘| format 1 labels. Check also 
all parameters in the job 
_ For ALLOC: a file with the same a file 1D already exists . _. + |. control device assignment set. 
"on this volume. ‘ eae | aa 





No empty label records in VTOC. fe Tits Ge Cent line Agree 4 Seetite _{< Eliminate unused files or expand VTOC 
. : Meee ee eR RET TE MERE ea Si Gt 
No space available on thisvolume.. 5 es taetey ete Eliminate unused files or change to a 
= S Dy Pe ye Oe Pe a ES ge PT ese ES noncontiguous request. 
( . ,No file control block (FCB) found for this internal filename. a Check LFD.job control statement... 
“ (LFD- name). ro : E c 3 Gtaex - : 4g oR. é #., 
“ For OBTAIN, the. disk address specie i is iovalig. aes ae he i . eee . o3 Provide. correct, disk address, 
: Ee ECE! Dee “arid rerun. © 
For track aligned files, SCRTCH is invalid. Use release that recognizes 
_| track aligned files. 
‘$YS' is specified as first three characters of file ID to System files may not be 
SCRATCH macro (PR Bes Teheran. Geallocated wie Sen teH macro. 
; 6 WE BOR 2 me nea Ponacwary “Teg Sa . : 
$VTOC i is named asi file to be scratched. Tong ite foe fp AS$VTOC file cannot be... 
faye ae “3 oes eae 2 8G : ei scratched. se a% Sie sas 
ea ae _.«, | > For RENAME, the file to,be renamed i isnotas ee .°c+-| Data set label diskettes cannot” 
: format Jebel file, beasts a _. _|.be scratched. — 
VTOC format error is detected. © eto te |) For diskette, check for duplicate 
or overlapping space or a 
duplicate name. 
For disk, list VTOC and check 
format 4 label. 
Request for extension of file will exceed number of allowable Create a new file with a single 
extents (16 for all but split files, which are allowed 13). extent large enough to 
accommodate the contents 
of the old file. 
Error detected in your parameter table. Review formats presented in 
this manual and in 
supervisor user guide, UP-8075 
(current version). 


sO, 
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B.3.3. Disk File Extension-Error Handling. 2.) <.. =: C 


Three types of extend failures can occur, each associated with a data meanegerert error 
diagnostic: ; ink 


DM45 EXTENT TABLE EXHAUSTED 


No space exists. in the logical extent table for additional space aequired by file 
extension. is | 


DM41 FILE SPACE EXHAUSTED ° 
‘No physical space exists for file extension. — 
DM11 SPECIFIED NON-EXTENDABLE 
DTF specifies the file as nonextendable by: 
— maintaining a secondary allocation increment of zero (via the EXT card) 
—_— defining the secondary allocation percent (UOS) as zero 
— sétting the nonextendable flag in the partition table flag byte. 
Errors occuring during file extend operations aré always associated with ‘inability to \ 
acquire output space for a buffer and consequent loss of output data. On extend failure 
errors, file extend procedures now minimize loss of output data to one record. 
B.4. ERROR FLAGGING PROCEDURES 
All OS/3 data management pgorams set bits ina sel field of the DTF file table to serve 
as error flags, providing ‘you with particular information on the error. Disk and tape 
programs set the bits in this field and then call the logging transient (B.3); card and printer 
modules go directly: to’ the logging transient. When an error: is detected during the 


execution of a data management transient routine, the logging transient is called after the 
setting of the error flag bits is completed or bypassed. ~ : 
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B.4.1. FilenameC 


The error flag field of the DTF file table is designated filenameC; it may be accessed by 
your program through the test under mask instruction: (TM), using for operand 1 your 7- 
byte logical filename, to which you have concatenated the letter C. Note that the size of 
filenameC varies with the type of file: for card and printer files, it is only one byte long; for 
tape and disk files, it is four bytes long. Table B-3 lists the significance of the bits that are 
set to binary 1 in filenameC for certain error and exception conditions. For information on 
paper tape error processing; refer t to 17.5. 9. , 


Table B—3. Significance of Bits in fileriameC (Part 1 of 4) 


Last block on Be ax ‘Reserved Line truncated . Record size 
track accessed ~ ; ‘| (data too large): invalid 
oe i (too large or 
= too small) 


Invalid 1D ————} Reserved Invalid control Reserved 
f ~s Invalid DTF Invalid — “ ‘Invalid Character mis- Validity check 
ee PCA/DTF DTF match {unique unit error) 
3 


Hones es 

error rey lt _ = 

evarfound," Sen cans Cine COOEEE SON 
Hope ee ee ee ee 


in CLOSE 


Invalid macro 
sequence 


Reserved - (DTFSD: reserved) Reserved Record size Reserved 
; WAITE ~ ae invalid . 
required © oe a (too small) 
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Table B—3. Significance of Bits in filenameC (Part 2 of 4) 





WO 
1/0 completed. . 
Unrecoverable 
Unique unit 
_ Record not 
"Reserved 
Reserved. - 
2 OOOO, 
a 






Gonnis 






STOP state 


= 


Word count 
= zero 











Data converter 
check 
(7-track only) 


I 
% 
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Table B—3. Significance of Bits in filenameC (Part 4 of 4) 


Invalid record size 


Logical end of file 


2 File space exhausted Logical end of volume 
(DTFIS) 
Logical end of volume 
(DTFIR and DTFM!) 


pee Processing inhibited Invalid subfile Wrong length error 


Sequence error Reserved Reserved 
(DTFIS and DTFIR 


7 ADD rejected Reserved Reserved 
(DTFIS only) 


B.4.2. Other DTF Fields 





Certain of the OS/3 data management modules place, in other fields of the DTF file 
table than filenameC, additional information that is of value to you in monitoring the 
processing of your files. The details are documented for each specific use in the 
appropriate section of this manual; these fields are designated filenameA, filenameP, 
filenameS, etc., and are addressed in the same manner as filenameC: by concatenating 
the letter designation to your 7-byte logical filename. 




















- S é 





























‘ 


eae 
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Appendix C. Code Correspondences 


(C.1. GENERAL | ie: Le 


This appehdie: presents a_cross- aetotericd table and figures seefil to you for visualiging the 
correspondences among the following codes ae used in data Process! ng and in 
OS/3: oe te wee 


me, Hollerith: pence: card. code 


1. EBCDIC ieaended: Binary Coded Decimal Interchange Code) 


=» ASCII (American National Standard Code for: lnforenations imicechanael 


= @§=6©Binary bit-pattern (bit-configuration):‘representation for an 8-bit system. 


a Hexadecimal, representation 


2 Csimpiessen: code fou: punched Garda: 


= Binary (image) mode for punched cards 


ree, 67: ead EBCDIC/ASCII/HOLLERITH CORRESPONDENCE 


a Table C—1 is a cross- “eefatance table depicting the: ecieeepandences: among the Héllerith 


punched card code, ASCII, and EBCDIC. The table is arranged in the sorting (or collating) 
sequence of the binary bit-patterns that have been assigned to the codes, with O0O0O0 0000 
being the lowest value in the sequence and 1111 1111 the highest. 


Note that the column headed Decima/ uses decimal numbers to represent the positions of 
the codes and bit patterns in this sequence, but counts the position of the lowest value as 
the Oth (zeroth) position rather than the first. Thus, the position of the highest value bit- 
pattern 1111 1111 is represented in the decimal column by 255, whereas it is actually the 
256th in the sequence. This scheme corresponds to the common convention for 
numbering bytes, in which the first byte of a group is byte O, and is convenient when you 
are constructing a 256-byte translation table. (See the MODE keyword parameter of the 
DTFCD declarative macroinstruction (3.3).) 
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The column headed Decimal also represents the collating sequence for the EBCDIC 
graphic characters shown in the fourth column of the table; the fifth column, Hollerith 
Punched Card Code, contains the hole patterns assigned to these EBCDIC graphics. Empty 
space in the: fourth: column represents: the positions, of the EBCDIC control characters; the 
EBCDIC space charater is represented in the fourth column by the conventional notation 
SP at decimal position 64, and the corresponding card code is “‘no punches.” 


The ASCII graphic characters, listed in the sixth column of Table C—1, are also in their 
collating sequence, and the hole patterns in the seventh column correspond to the ASCIl 
graphics. The ASCII space character is represented by the notation SP in the sixth column 
at decimal position 32; the corresponding card code is, again, ‘‘no punches.” The empty 
space in the sixth column represents the positions of the ASCII control characters. The 
shading in the ASCII graphic character column indicates where the 128-character ASCII 
code leaves off: there are no ASCII graphic or control characters that Gorrespond to the bit 
patterns higher in collating sequence than 0111 1111 (the 128th in Table C—1). 


-€.2.1. Hollerith Punched Card Code 

The standard Hollerith punched card code specifies 256: hole-patterns in:12-row punched 
cards. Hole-patterns are assigned to the 128 characters of ASCII and to 128 additional 
characters for use in 8-bit.coded systems.: These -include:the EBCDIC set. Note that no 
sorting sequence is implied by the Hollerith code itself. 


Boel se eacoa. & 
Bebe. be - 


Peete a SESE ete GS a oa shooFF GL AEY S eae aE as 4 Powe” Eo 2 


2 E Mo 
= See : ste ke ore Baer fet rk fc ger em Tye) OR ay Shope et oa gt a eo a eb aan 
C. rp ae BCDIC. . etre Wage COR GE ERE Og Ce a ee a eae a Oe eke! GS eae aet ee eS ara aers : woPao. a 


EBCDIC is an extension of Hollerith coding practices. It comprises:256-characters, each of 
which is represented by an 8-bit pattern. Table C—1 shows the EBCDIC ululaies characters 
only; the EBCDIC control characters are not.indicated..;. pd eee Rare pant hae, 


C.2.3. ASCII 


ASCII comprises 128 coded characters,.each represented by, an 8-bit.pattern,;-and includes 
both control characters and graphic characters. Only the latter are shown in Table C—1. 
»«cASCIL is used. for.information Ingsrenange among: data: pronessing: communication: Seiiem: 
he pangs associated L equipment. mist wleas eo? oho etet ¢ . ee wee 
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Table C—1. Cross-Reférence Table: EBCDIC/ASCII/Hollerith (Part 1 of 5)” 


ee e EBCDIC |. Hollerith ASCII... |" © Hollerith 
.,Desimal, |. : Graphic . Punched Card yerGraphic |. Punched Card 


F : 


ONDINAMAKRwWN=AO0]. 


0000 0000 
0000 0001 
0000 0010 
0000 0011 
0000 0100 


“| 00000101 


0000 0110 
0000 0111 
0000 1000 
0000 1001 


‘| 0000 1010 — 


0000 1011 
- 0000 1100 
0000 1101 
0000 1110 


| .0000 1111 


0001 0000 
- 0001 0001 
0001 0010 
0001 0011 
0001 0100 
0001 0101 
0001 0110 
0001 0111 


9001 1000 


“9001 1110 
0001 1111 
0010 0000 
0010 0001 
0010 0010 
-0010°0011 
0010 0100 
.0010 0101 
0010 0110 
0010 0111 


0010 71000 ~ 


0010 1001 
0010 1010 
0010 1011 


00101101 


0010 1110 
0010 1111 
0011 0000 
0011 0001 


0011 0010 


0011 0011 


0011 0100. 
0011 0101 
0011 0110 


Character -oas Code | Character : Code 


12-0-9-8-1 
12-9-1 
12-9-2 
12-9-3 
12-9-5 | 
12-9-6 
12-9-7 
12-9-8 
12-98-1 


12-9-8-7 | 
12-11-9-8-1 
11-9-1 
11-9-2 
11-9-3_. 


11-9-8-2 
11-98-3 


12-0-9-8-1 
12-9-1. 
12-9-2 
12-9-3 3° 


0-9-5 
12-9-8-3 
12-9-8-4/ 
12-9-8-5.. 
12-9-8-6 
12-9-8-7 » 
12-11-9-8-1 
11-9-1 
1192.7 


‘|. 11-9-3 


11-9-8-1 ° 


— 9-8-7 
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Table C—1. Cross-Reference Table: EBCDIC/ASCII/Hollerith (Part 2 of 5) .. 

























“EBCDIC ASCII 

























- EBCDIC. -Hollerith ASCII | 


im | ‘Hollerith 
Binary © Graphic Punched Card. Graphic Punched Card 
mf 3 Character: ‘Code Character — __ Code 





















0011 1100 9-8-4 
0011 1101 9-8-5 
0011 1110 9-8-6 
0011 1111 9-8-7 


__0100.0000 
0100 0001 
0100 0010 
0100 0011 
0100 0100 
0100 0101 
0100 0110 


0100 0111 
0100 1000 


0100 1001 
0100 1010 
0100 1011 
0100 1100 
0100 1101 
0100 1110 
0100 1111 
0101 0000 
0101 0001 


No.punches . 







































ae 



























12-11-9-1 | 


0101 0010 12-11-9-2 
0101 0011 12-11-9-3 


.0101 0100 
0101 0101 


12-11-9-4 
12-11-95 


0101 0110 12-11-9-6 - 
~ 0101 0111 412-11-9-7 
0101 1000 


12-11-9-8 





0101 1001 






Del ON<K<xKS<clHae*zOVOZerale-roOTNMooODdIOr vu At 





0101 
0110 0000 
0110 0001 
0110 0010 
0110 0011. 
0110 0100 
0110 0101 
01100110 
0110 0111 
_0110 1000 

















o 













sa +o alow 



















0110 1001 a 

- 0110 1010 as 12-11-1 

30110 1011 “ok 12-11-2 - 

~0110 1100 7 ae 12-11-3. ¢ 
0110 1101 om 12-11-4 © ‘ 
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Table C—1. Cross-Reference Table: EBCDIC/ASCII/Hollerith’(Part 3 of 5) 


Me a _ EBCDIC..,.| — Hollerith » ASCII! | :Hollerith 
etn i; | Binary |. Graphic: Punched:Card |_ Graphic Punched Card 


01101110 |. TT Ogg 


01101111” 
0111 0000 
0111 0001 
0111 0010 - 


0111 0011 
0111 0100 


01110101 . 


01110110 
01110111 


0111 1101 
0111 1110 
0111 1111 


1000 0000 
1000.0001 


1000 0010 


1000 0011 | 
1000 0100 : 


1000 0101 


1000 0110 — 


1000 0111 


1000 1000 -° 


1000 1001 


1000 1010 : 


1000 1011 
1000 1100 
10001101 


1000 1110 


1000 1111 


1001 0000 . 
7007 0001 
1001 0010 


1001 0011 


1001 0100 | 
1001 0101 


—-aroalr*o ao ola. 


7 OD OJ355 7 K%™ 


| 8-4 


0-8-7 
12-11-0 


12-11-0-9-1 _ 


12-11-0-9-2 


'12-11-0:9-3 
'12-11-0-9-4 


12-11-0-9-5 
12-11-0-9-6 


12-11-0-9-7 © 


12-11-0-9-8 
8-1 
8-2 
8-3 


12-0-8-4 
12-0-8-5 
12-0-8-6 
12-0-8-7 
12-11-8-1 


12-11-6 
12-11-7 
12-118 
12-11-9 
12-11-8-2 
12-11-8-3 
12-11-8-4 
12-11-8-5 
12-11-8-6 
12-11-8-7 


11-0 
11-0-1, 
12-9-7 
11-0-9.8-1 
0-9-1 . 


0-9:8-4 
12:9-8-1 
12-9-8-2 
11:9-8-3 
12-11-0-9-8-1 
91°: 
11-9-8-2 
9-3. 
9-4 

95: 
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Table :C—t. - Cross-Reference Table:» EBCDIC/ASCII/Hollerith (Part 4 of 5) 


# 

A 

4 
ee 


~ascu |. 
Graphic 


* .EBCDIC 
Graphic: ** 


- Hollerith 
‘Punched Card 


-~ Hollerith: 


Decimal |. Binary Punched Card 


160 
161 
162 
163 
164 


1010 0000 


1010 0001 
1010 0010 
10100011 


1010 0101 
10100111 


1010 1000 
1010 1001 


_ |..1010 1010. 
~ 4010 1011 
- 10101100 : 
~ 10101101 - 
- 10101110 . 


1010 1111 


' 1017.0000 . 


1011.0001 


~ 1011 0010 


* 4010.0100 . 


40100110 


} 


10110011’ 


10111110. 
© 4011.1111 
- 1100 0000 
* 1100 0001 


1100 0010 


- 10110100 — 
- 1011 0101. 
_ 10110110. 
101101117 
«1011 1000 


» 1100 0011 
:.1100 0100 
1100 0101 
- 1100 0110 
41000111 


11001000. . 


» 1100 1001 
“1100 1010 
1100 1011 


1100 1100 


- 11001101 
-1100 1110 


1100 1111 


*1101 0000 
“1101,0001 


' Character 


Code 


12-11-0-8-1 


-12-11-0-1~ 
12-11-0-2 
12-11-0-3 
12-11-0-4 


~.)42-11-0-5° 


12-11-0-6 
12-11-0-7 
12-11-0-8 


Sten ean as 


-rTlonmoolo p— 


42-11-0-8-2 _ 


12-11-0-8:3 
12-11-0-8-4 
12-11-0-8-5 


12-11-08-6 _ 


42-11-08-7 
12-0 
12-1 
12-2 


12-8 
12-9 
12-0-9-8-2 
12-0-9-8-3 
12-0-9-8-4 
1 2-0-9 -8-5 
12-0-9-8-6 
12-0-9-8-7 
11-0 
11-1 


Character 


Code | 


..12-0-9-1..... 


12-0-9-2 
12-0-9-3 
12-0-9-4 
12-0-9-5 
12-0-9-6 
12-0-9-7 
12-0-9-8 
12-8-1 
12-11-9-1 
1 2-1 1-9-2 
12-11-9-3 
12-11-9-4 
12-11-9-5 
12-11-9-6 


1211-9-7 


12-11-9-8 
11-8-1 
11-0-9-2 
11-0-9-3 


11-0-9-4 


11-0-9-5 
11-0-9-6 
11-0-9-7 
11-0-9-8 
08-1 
12-11-0 
12-11-0-9-1 
12-11-0-9-2 
12-11-0-9-3 


~12-11-09-4 


12-11-0-9-5 
12-11-0-9-6 
12-11-0-9-7 
12-11-0-9-8 


12-0-8-6. 
12:0-8-7 

12-11-8-1 
12-11-8-2 
12-11-8-3 
12-11-8-4 
12-11-8-5 
12-11-8-6 
12-11-8-7 
11-0-8-1 
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Table C—1. Cross-Reference Table: EBCDIC/ASCII/Hollérith (Part-5 of 5) = > 


Sg ei gerry eo RSD IE ea) oh: rater hase 
hee ry | EBCDIC. | -Hollerith 
= Graphic:,, |, Punched Card | 


AScit? | Hollerith 
(Graphic: -}°.. Puriched'Card °.| 


1101 0010 
1101 0011 
1101 0100 
1101 0101 


41070110” 


1101 1100 
1101 1101 


1101 1110... 


11011111 
1110 0000 
1110 0001 
1110 0010 
1110 00114; 
1110 0100 
1110 0101 
1110 0110 


14900111 f 
“4110 1000 
1140 1001 


1110 1010 


1110 1011 
1110 1100 


1110 1101 
1110 1110 
1110 1111 
1117 0000 
1111 0001 
1111 0010 
1111 0011 


Character 


s 
r 
U 
V 
Ww 


q 


.N<&X 


11,11.0100...4 


—-1411.0101.. | oe. 
11110110 


11110111 


111-1 1000. ---}--~---- 


1111 1001’ > 


OO YAH p wr — 


Code 


11-7 
11-8 
11-9 
12-11-9-8-2 


(12-11:9-8:3 © 


12-11-9-8-4 
12-11-9-8-5 


12-11-9-8-6*: 
12-11-9-8-7 ._ 


0-8-2 


0-2 
0-3 
0-4 


0-5 


OG. 


xjhee7 idsct 


0-8; 


11-0-9-8-2 
11-0-9-8-3 


11-0934 . | 
11-0:9-8-5 
11-0:9:8:-6° << 


11-0-9-8-7 


i=) 


Character 


Code 


TNOB7ia oo! 
12-11-0-8-1 
12-11-0-1 
12-11-0-2 
12-11-0-3 
12-11-0-4 
12-11-0-5 
12-11-0-6 
12-11-0-7 
12-11-0-8 
12-11-0-9 
12-11-0-8-2 
12-11-0-8-3 
12-11-0-8-4 
12-11-0-8-5 
12-11-0-8-6 
12-11-0-8-7 
12-0-9-8-2 
12-0-9-8-3 
12-0-9-8-4 
12-0-9-8-5 
12-0-9-8-6 
12-0-9-8-7 
12-11-9-8-2 
12-11-9-8-3 
12-11-9-8-4 
12-11-9-8-5 
12-11-9-8-6 
12-11-9-8-7 
11-0-9-8-2 
11-0-9-8-3 
11-0-9-8-4 
11-0-9-8-5 
11-0-9-8-6 
11-0-9-8-7 


12-11-0-9-8-2 
12-11-0-9-8-3 
12-11-0-9-8-4 
12-11-0-9-8-5 
12-11-0-9-8-6 
12-11-0-9-8-7 


11111010 - <P '92-11-0-9:8-2 
W114 OVD fe ees vy soe ef 4 D-4.4-0-9-8-3F 
11111100 | "42-1 1-0-9-8-4 
11111101 .°} 12-11-0-9-8-5 
11111110. > 12-11-0-9-8-6 
11111111 © 12211-0-9-8-7 
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C.3. OTHER CARD CODES 

Two other punched card coding systems can be handled with OS/3 data management and 
all card. reader and card punch subsystems in the SPERRY UNIVAC 0730 System: the 
compressed code and the column: binary, or. r image, code. 

C.3.1. Compressed Card Code 


Figure oe indicates the construction of the compressed card code; each card column is 
represented by an a: bit pattern in one byte of | main storage. 


om COLUMN PUNCH POSITIONS 


MAIN STORAGE 
BYTE 
‘BIT POSITIONS 





NOTE: = 


_ PUNCH POSITIONS 1. THROUGH 7 ARE INDICATED IN: 
BITS 1 THROUGH 3, ACCORDING T TO THE: FOLLOWING TABLE: 


PUNCH | 
‘ROWS 1 THRU 7 





Figure C—1. Compressed Card Code 


UP-8068 Rev.4 | SPERRY UNIVAC OS/3 C-9° 


BASIC DATA:MANAGEMENT © 


C.3.2. Column Binary (Image) Code 


pute 


Figure C2 indicates the construction of this code. Note that each card ae requires 
two bytes of main storage; an I/O area of 160 bytes is required for an 80-column::card. 


COLUMN PUNCH POSITIONS 


2 
7 
4 
5 
6 
8. 
9 





GEDBE COGS ESO 


DATA BYTEO — ’ DATA BYTE 


NOTE: 


BITS 0 AND 1 ARE CLEARED TO ZEROS ON AN IMAGE READ. 


Figure C—2. Column Binary (Image) Card Code 


C.4. DATA CONVERSION 


In OS/3 data management, there are five ways in which your data, held in main storage 
in 8-bit bytes, may be converted into hole-patterns in punched cards, and vice versa: 


Standard mode (EBCDIC) 
Standard mode (ASCII) 
Compressed code mode 
Binary (image) mode 


Translate mode for reading or punching 


In EBCDIC standard mode (MODE=STD), data in main storage in EBCDIC code is punched 
into cards in the Hollerith punched card code. Cards are read in Hollerith, and the data 
stored in EBCDIC. 
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In ASCII standard mode (MODE=STD and ASCII=YES), data management translates data 
stored in the 8-bit ASCII code in main storage to EBCDIC, and then the cards are punched 
in Hollerith. The reverse process is used when cards are read, unless a hardware ASCII 
translate feature is available on the card reader, when data management omits the 
EBCDIC-to-ASCII translation. 


In the compressed code mode (MODE=CC), an 8-bit data byte is converted by data 
management into eae bce ease C—1). 


between 12 data bytes in main storage are is stored in the least significant six bits of 
two 8-bit bytes) and the 12 possible row punches in a card column (Figure C—2). 


In the translate mode (MODE=TRANS), you make your own assignment of 8-bit patterns to 
the 256 hole-patterns listed under EBCDIC in Table C—1, in the order these are shown in 
the table. 


The preceding considerations should be of little concern to you because, with OS/3 data 
management, you can always use any mode with any peripheral equipment in your 
installation’s configuration. 


The 96-column card format (as shown in Figure c—3) hold 96 cperacters of data at six 

bits per character. The characters are arranged on the card as three rows of 32 characters 

each. The fact that each character can: be represented in six bits is the reason no binary 

read mode is provided. Depending upon the translate features.in the hardware, and MODE é 
keyword specification, each 6-hole character on a card is transferred into the user’s I/O ad 
area as an EBCDIC or ASCII 8-bit byte. af 
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1234567890 


304 5 € 7 B 8 15 HH 12 13 14 1S 1H 17 WB WW IO QE 22 23 24 25-26 27 28 29-30 31 32 


ABCDEFGHIJKLMNOPORSTUVWXYZ 


33 34 35 3 27 38 29 40 41 42 43 44 45 46 47 48 49 50 51 £2 53 54-85 56 57 58 $9 GO 6 62 63 64 


¥6¢.<(4+11$*);7-/&.% _>?:#@'=" 


SS 66 67 68 59 7D 71 72:73:74 75 76 77 78-79 BO H 82 83 84 85 HG BT BS 8D 80.91 92:93 94 95 86 


CRORS) 


S7 $8 99 300 101 102 103 104 108 106 167 108 TOG 1G ThE ITTF HM NS HG U7 1H VB 12] 11122 1TId 12S 126 127 12e 


19 20 21 22 2324.25 26 27 26 24 30 31 32 


Qo Rs 85: #5 L ss 2 57 Bis cow G2 63 64 


os 66 B ca R10 P22 Bia Rie Bie B00 Baz Bisa Bas Fue Bo P52 93 94.95 58 
0D 3700 


@  NUMERICCHARACTERS [1|2/3[4/5]6]7[8|/9]/0| 


“NAODT-NSObM-NAHPO 
“~“NDOPOM-NAOPO-NHNSOd’O 





Zone @eiB 

Punches @lA A 
eis 

Digit @; 4 4 

Punches ei 2 2/2 2 
ei 1 1 1 


O @ ALPHABETIC CHARACTERS | A|B/C{D/E|F/G]H|! [J | K}L] MNO} PlalR{s |T]ulv| wi x] yi z| 


PO, 


Zone je B 
-Punches el A 
eis 
Digit @14 
Punches @)2 
@!1 


8) _  §PECIAL CHARACTERS 


Zone 1 eis B 
Punches @lA A 
eis 8 
Digit @;4 4 
Punches @i2 2 
@; 1 1 





Figure C—3. 96-Column Card Punch Codes 





ue 


4 








7 ‘ 
: 
i 





i ‘ 
+ 4 
4 





ms, 
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“Appendix D. Labels for Disk Files 


D.1. GENERAL . 


This appendix describes the system standard labels for disk files in OS/3 as well as the 
optional user standard labels that are supported by OS/3 data management for.processing 
disk files described by the DTFSD, DTENI, and DTFDA macros. Note that OS/3 ISAM does 


not support user labels. for DTFIS files. ne user standard labels. are described, sin D. 4.) 


Because your files within a ‘disk volume may be stored in various iocations. a airectory 


listing the addresses of the fragments of the files is required. This directory, called the 


volume table of contents (VTOC), and your files within a disk. volume require various 


standard labels. in predefined formats. to describe me properties of ‘the. files and the 
volumes. on which they. reside. , ' oi : eo ae rer . 


The system standard disk. labels ‘include the volume label (VOL1 label) ‘ands seven ivoes of 
format labels. These labels may, according to their use, be separated into two distinct 
groups: 
# Volume Information Group 

— VOL1 label 

— Format 4 label 

— Format 5 label 

— Format 6 label 

— Format 0 label 
= @§=«©File Information Group 

— Format 1 label 

— Format 2 label 


— Format 3 label . 


The VOL1 label has a length of 84 bytes; all format labels are 140 bytes long. 
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D.2. VOLUME INFORMATION GROUP 


The doltime information group, comprising the VOL1 label and the format 4, 5, 6, and O 
“labels, identifies the volume and defines the VTOC, the status of the VTOC, the available 
| space within the volume, and the device-dependent characteristics of the volume on which 

the group resides. 


Standard linkages maintained within the group are shown in Figure D—1. The VOL1 label, 
normally the first label in the group to be referenced, is written at cylinder O, track O, 
record 3 on each volume. The VOL1 label identifies the volume and contains a link to the 
format 4 label. The format 4 label defines the extent occupied by the VTOC and the device- 
independent characteristics of the volume; it also supplies a link to the first format O label. 


Each label in the VTOC that describes label records not in use is defined'as a format O 
label and is ies to the next avallavie noua 0. 


“The: format’ 4 label also’ supplies a link to the first format 6 label, ‘which defines space 
available within the extent areas of files sharing extents (split cylinder allocation). If more 
format 6 labels are required, they are linked in the same manner as format O labels. The 
format 6 label and its link from the nonmpat 4 label hale be. piesent only if ae ‘cylinder 

“allocation nee taken Piaeos : 
The first (or oily) format: 5 label immediately follows the format 4 label, supplying. an 
‘implied linkage. The format 5 label defines unused space on the volume in terms of full 
cylinders. Successive format 5 labels, if required, are linked one to another. The VTOC 
extent, as specified in the format 4 label, supplies an additional linkage pacause | it is this 

alee that must be Sood in order to access the file IMormation groups. ° 


FORMAT 4 LINK 


CYL O TAACK 0 REC 3 








FORMAT 4 


VTOC EXTENT 
FORMAT 6 LINK 


FORMAT 0 LINK 


FORMAT & 













FORMAT 6 






FORMAT 0 


FORMAT 5 LINK 





FORMAT 5 


FORMAT 6 LINK FORMAT 0 LINK 





FORMAT 6 FORMAT O 


Figure D—1. VTOC Volume Information Label Group 
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D.2.1. VOL1 Label 


As each disk volume enters the system, it is given a unique identification code or volume 
serial number and the rudiments of a VTOC. The volume serial number and the address of 
the VTOC are placed in he VOL1 label. ‘ 


The VOL1 label, identified by a. key field and label identification field containing “VOLt", i is 
written by the disk initialization routine at cylinder 0, head O, record 3: 


The VOL1 label is the standard volume label in the OS/3. All netersnce: to the VTOC of a 
given volume is made by first. obtaining the VOL1 label, verifying the volume serial 
number, and, because the location of the VTOC may vary from volume to volume, using 
the VTOC address contained in’ the ee label to locate the VTOC itself. : 


The format of the VOL1 label is shown in Figure [ D—2: Table D4, summarizes its 
contents. 


saa “ label identifier . ‘ so ~ label number: 


~ < “volume serial number _- 
volume security 


volume table of contents address 


reserved 


owner name and 
address code 


+ ee . 


reserved 





Figure D—2. VTOC VOL? Label 
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Table D—1. Contents of VOL? Label 


DLS$VL aes EBCDIC Key — contains VOLt. 


DL$VL1 peente Label identifier — VOL. 


















ae Label number — always 1. 


DLS$VSN - Volume serial number — a unique code 
"assigned to a disc pack when it enters 
the system. The same code should appear 
visually on the disc pack for operator 
identification. 


Volume security — reserved for future use. 


VTOC address — This field is used to point 

to the format 4 label, which starts the 

VTOC. The address is in the form cchhr in 
bytes 15 through 19. Bytes 20 through 24 are 0. 


Reserved 


Optional owner name and address code — 









Discon- 
tinuous 
binary* 









DLS$VSB . Disc prep | aa | - Binary 
_ tte 
an installation-supplied user identifier. 


inane 


* For discontinuus iiarys sits subfield is treated as a distinct binary entity. In the notation cchhr, each 
different letter represents a subfield. 


EBCDIC 








D.2.2. Disk Format 4 Label 


The format 4 label describes the VTOC itself and is the first record of the VTOC. An 
indicator in the format 4 label states whether the format 5 label contains valid 
information. In addition to describing the area occupied by the VTOC and its current 
status, the format 4 label contains information on all device-dependent characteristics of 
the volume on which it resides. 


The format 4 label is written by the disk initialization routine at the disk address. specified 
in the VOL1 label. Only one format 4 label may exist on a given volume. 


The address of the first available label record (i.e., a format O label) is placed in the format 
4 label for use by OS/3 disk space management. An additional linkage is created and 
maintained by disk space management that specifies the first active format 6 label and is 
used only during split-cylinder allocation of data files. Figure D—3 shows the format 4 
label; Table D—2 summarizes its contents. 
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BYTES 








key field 


format ID ! last active format 1 


available file label records 
48 


highest alternate track 
52 


number of alternate tracks reserved number of extents 


reserved i device size 


60 


device size: track length 


record overhead 
68 


tolerance blocks 


72 


pointer to format 0 label 





80 


reserved 


96 


pointer to format 6 label 


104 


VTOC extent 


112 


136 








Figure D—3. Disk Format 4 Label 
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Table D—2. Contents of Disk Format 4 Label (Part 1 of 2) 











_ Initialized 
by 





Description 






















" Hexadecimal 





Disc prep 





DL$KY4 Key field — Each byte of this _ 


field contains 04.6: 


| DLgID4 ~ Disc prep - EBCDIC Format ID — always 4 for 
aa format 4 label. 
| 45-49 | 


- DLSLF4 












Discoitndous 
eee , 


DL$HA4 





Last active format 1 — the address, 
in the form CCHHR, iti fora genic 
on filename. 


Space mamt. 

















Available file label records — | 
number of unused records in the VTOC. 
















Discontinuous 


si Highest alternate track — address, in 
binary 


the form CCHH, of alternate tracks 
set aside incase of bad tracks. 


DL$AT4 86-57 ‘Number of alternate tracks. 


DL$V1I4 





Disc prep 







uae mgmt Reserved for VTOC indicators — 

















Bit Contents edapeningy, 






A format 5 label, if 
present, contains 
invalid information. 







Unused 


. DL$xc4 Disc prep Binary | Number of extents — contains 01, 16 to 
indicate the one extent in the VTOC. 
ee 


DL$DS4 62-65 


_ eye 













Device size — indicates the number of 
cylinders and the number of heads per. 
cylinder on the device, in the form 
CCHH. 


Disc prep 

















Track length — number of available 
bytes on a track exclusive of home 
address and record 0. 







Bem, 
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Table D—2. Contents of Disk Format 4 Label (Part 2 of 2) ©... ° 


initialized | se i esac 
by a ror escription _ 


DL$RO4 Disc prep 5 | Record overhead — ILK describes 
; ae ee ee | ra . | overhead bytes ‘on track, where 
lis for keyed record which is: 
. -not the last on track,Lisfor =. ~ |.. » > 
_ keyed record which is the last : 
“on track, and K is a decrement 
applied to records which have 
no key. 


DL$F G4 Disc prep 
Meaning 


Reserved. 
Device-dependent 
characteristics 
Disc prep Tolerance —adevice-dependent — 
. factor which is used-to-calculate 
effective record lengths for that 
device. 


DL$LT4 | Disc prep ___ Labels per track — a device- = 
dependent factor specifying the 
number of 140-byte labels possible 
in.a VTOC track. 


DL$BK4. Disc prep Blocks per track — a device- . 
dependent factor specifying the 
number of directory. blocks of a 

as partitioned file which canbe. 
written on a track. 


DL$FO4 Disc prep Format zero address in the form 
CCHHR — points to the first available 
format zero record in the VTOC. 


DL$F64 Space mgmt 100-104 Format 6 address in the form | 
CCHHR — points to the first 
format 6 label created by 
space management. 


DL$V X4 Disc prep 105—114 VTOC extent — describes the extent 
occupied by the VTOC itself. The 
format of this field is identical 
to the fields describing the extent 
in the format 1 and 3 labels. 
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D.2.3. Disk Format 5 Label 


The format 5 label is the second record in the VTOC and is used to maintain control of the 
available extents in the volume at any time. 


The format 5 label is initialized by the disk initialization routine and maintained by the disk 
space management routine. Each format 5 label may define up to 26 available extents. 
Format 5 labels may be linked together should more than one become necessary. Figure 
D—4 shows the format 5 label; Table D—3 summarizes its contents. 


BYTES 


available extent 


available extent 


available extents 


oes ; 
format ID 


available extents 


format 5 pointer 





Figure D—4. Disk Format 5 Label 


on 


reamieen 
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Table D—3. Contents of Disk Format 5 Label 


DL$ID5 Disc prep Hexadecimal Key identification — Each byte of this 
field contains 05.46 


DL$XT5 Disc prep Discontinuous Relative track address — start of extent. 
binary 


mae E5 eee prep Binary Number of tracks in extent in addition to 
the cylinders. 
Space mgmt 9-13 Available extent — describes another extent 
in fields with the same format as bytes 4 
through 8 above. 


Ld Space mgmt | taas | Six more available extents. 


DL$FI5 EBCDIC Format ID — always 5, for format 5 label. 
DL$XS5 45—134 : aa Eighteen more available extents. 


“a bene si 


D.2.4, Disk Format 6 Label - 


















Pointer — indicates the address of another 
format 5 label, in the form CCHHR. Binary 0 
if no further label. : 


Discontinuous 
binary 









The format 6 label is used to control split-cylinder allocation. Each format 6 label contains 
a code that identifies all member files sharing the same extent area. Each member file is 
allocated from 1 to n tracks within each cylinder allocated to the set, where n is the 
number of tracks per cylinder, minus one. Additionally, a head pool is maintained that 
specifies all tracks not currently allocated and available for use by new members of the 
same split-cylinder set. A format 6 label will be created for each split-cylinder set defined. 


The format 6 label is created and maintained by the disk space management routines. 
Each label contains the disk address of the format 3 label that defines the extents 
allocated to that split member set. The disk address of the first format 6 label is 
maintained.in the format 4 label. If more than one format 6 label is required, they are 
linked together. 


Note that no extent information is maintained in the format 1 label of a split-cylinder file 
and that all members of a split-cylinder set share a common format 3 label. Figure D—5 
shows the format 6 label; Table D—4 summarizes its contents. 
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este i = 
or ee neue 


9 additional head pool entries 


* primary member for- 







28 






32 





19 additional format 1 tabei 
disc address-entries 


” format 6 pointer 





"Figure D—5. Disk Format 6 Label 


Table D—4, Contents of Disk Format 6 Label 


=== = 


ss DL$HH6 - 












Description 







Key identification — always 060606, ., ; 





Device high head. 










~ Set identifier — identifies each 
‘member file of the split-cylinder set. 























DL$I DF36 | Discontinuous Disk address of the format 3 label 












bo. Wa Jaco eee ney _ shared by all member files _ 
DL$LHA6 Hexadecimal Low head available in the speciued 
ee oe extent areas. ot 
= hee on # Hexadecimal 1 High head available ‘in the 





specified extent areas. 


Nine additional entries for low and 
high available head. 


ial Hexadecimal 


Hexad eci simal 


PTs _ 


eice Discontinuous 
binary 


Format 1 disc. address of primary 
member (CCRH) 

19 additional split set format 1 
‘disc address entries in the same 
format as bytes 30-33. 







“DL$IDF16> 










Format 1 label disk addresses of up to 19 
additional members of the split-cylinder 
set in the same format as bytes 30—33 










Pointer to next format 6 label 
in the form CCHHR., 
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= D.2.5. Disk Format 0 Label 
_ The format O label is used. to identify label records in the VTOC not currently in use. 
; Format O records are initialized by the disk initialization routine: The address of the first 


format O is placed in the format 4 label, and each format O label is linked to the next. The 
remainder of the label is filled with binary O's. Figure D—6 shows the format O label; 


. Table D—5 summarizes its contents. ~ © | 


BYTES 


pointer to next available format O label | ° 





reserved 





Figure D—6. ‘Disk Format O Label 


Table D—5. Contents of Disk Format O Label . 


Disc prep 0-4 Discontinuous Disc address in the form CCHHR of 
binary the next available format 0 label 
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D.3. FILE INFORMATION GROUP 


The file information group (Figure D—7) is composed of the format 1, format 2, and format 
3 labels. The format 1 label is normally the first referenced label of the group. It is 
obtained by executing a key search for the file ID in the VTOC extent defined in the format 
4label. i on ke ee | 


The format 1 label defines the characteristics of the file and may define up to three 
extents occupied by the file. The format 1 label is linked to the format 2 label, which is 
used to further define the file. These two labels are present for each file in the volume. 


The format 3 label is used to define the extent area occupied by the file and is an optional 
label, except that it will exist for all files created by using split-cylinder allocation. For all 
other files, the format 3 label will exist only if the file occupies more than three separate 
extent areas. 


NON:SPLIT FILES 
FORMAT 1 


KEY 
(FILE 1D) 


FORMAT 2 LINK 
























KEY 
(FILE 1D) 


FORMAT 2 LINK 






FORMAT 2 FORMAT 2 


FORMAT 3 LINK 


OCCUPYING THREE 
EXTENTS OR LESS 


FORMAT 3 


OCCUPYING MORE THAN 


SPLIT-CYLINDER FILES THREE SEPARATE EXTENTS 


FORMAT 1 FORMAT 1 FORMAT 1 
KEY KEY KEY 
(FILE 1D) (FILE ID} (FILE ID 


FORMAT 2 LINK FORMAT 2 LINK FORMAT 2 LINK 




















FORMAT 2 FORMAT 2 FORMAT 2 


FORMAT 3 LINK FORMAT 3 LINK FORMAT 3 LINK 


FORMAT 3 


Figure D—7. File Information Group Label Chain — 
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‘a : D.3.1. Disk Format 1 Label 


A format 1 label exists for each file ina volume. As many as three extents of a file may be 
described in the format 1 label, provided that the file is not a member of a split-cylinder 
ee a“ ne ee ra ba oe ; ede 

The format 1 label is initialized by the disk space management routines. It is maintained by 
both the space management and data management routines. The format 1 label contains a 


pointer to the format 2 label. Figure D—8 shows the format 1 label; Table D—6 
summarizes its contents. . | | 


BYTES 





0 file 1D (key field 44 bytes) 














serial file number 






volume sequence no. 























Sa at | . 

56 ; a expiration date er 
ery 68 ° PCA 2 specifications 
ae Bs 

7G PCA3 specifications 

80 PCA 4 specifications 

a PCA 5 specifications 

i PCA 6 specifications 

92 

96 ; PCA 7 specifications . data set indicator 

“Dee [== [a | 

ae ere 

116 . : 

second extent (10 bytes) s 
.. 128 third extent.(10 bytes) ~~ s 


Figure D—8. Disk Format 1 Label 
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Table D—6. Contents of Disk Format 1 Label (Part? of 5) = pS 


“ Initialized’ | 


by Peslnsien 


DLSKEY1 Space mgmt EBCDIC File identifier — Each file must 
have a unique 1- to 44-byte name 
in this Key field, the first six bytes 
of which may bealock ID.A . 
search of the VTOC is made on 
this name. oe 


DL$ID1 EBCDIC Format identifier — always 1, for 
format 1 label. 


DL$FS1 Data mgmt _ EBCDIC File serial number—identifies the 
volume on which the file starts, is 
; a a 6-digit alphanumeric number, and 
is the same.as the volume serial num- 
. ber of the volume on which the file 
starts. The first volume of a file 
Etoae aac ls ; is defined by the first job control 
‘ DVC statement in the device assign- 
te. = ment set-for the file. 
DL$VS1 1-5 i Volume sequence number — indicates the 
Ret sipoet number of this volume relative to the 
a enna ai , - first volume in the file. The first volume 
ue of afile is defined by the first job control 
a fp a __DVC statement in the device assignment 
set for the file. f 
DL$CD1 Space mgmt Discontinuous _ Creation date — format is YDD (year- 
binary |. day-day), where Y is'0 to 99, and DD 
a is 1 to 366. . 
DL$ED1 ‘56—58 ~ Discontinuous ~ Expiration date — the date when the 
binary ~ file may be deleted. Format is the 
same as the creation date. 
DL$XC1 7 ing Extent count — specifies the number 
of extents currently constituting 
the file, or portions of it, on this 
So volume. 


DL$OC1 Space mgmt “Binary _ Option codes 
Bit Content Meaning 
. . : Preformatted by VTOC 
: Allocation by cylinder 
; ; | New file 
Partitions cylinder aligned 
: Unused 
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Table D—6. Contents of Disk Format:1 Label (Part: 2 of 5) 


initialized 


by Description : 


come 


DL$PC1 Data mgmt PCA count — number of partitions 
— - _ which constitute the file. 


DL$FT1 ~ Data mgmt” Hexadecimal | File type. 


Hexadecimal 
Code . Meaning 


20 : Sequential (DTFSD) 

40 Direct access (DTFDA) 

60 i Newindeited (DTFNI) 

80 Indexed enna (DTFIS) 


90 IRAM (DTFIR) or 
MIRAM (DTFMI) 


SAT (DTFPF) 
.-Undefined: . 


EGER, 


Hexadecimal. File type | 


Hexadecimal ae 
‘ Code Meaning 


00. RAM file, nonindexed 
VA Gade ... [RAM file, indexed. - - 


80 -MIRAM file, IRAM 
characteristics 


MIRAM file, MIRAM 
- characteristics 
NOTE: 
This:byte is meaningless unless byte 62." 
equals X‘'90'. 
DL$BL1— |-— Datamgmt - -~ | © Reserved for PCA1 block length — ~ 
size of fixed-length blocks or 


maximum size of variable-length 
blocks. 


DL$RL1 Data mgmt 66,67 Reserved for PCA1 record length — 
size of fixed-length records or 
maximum size of variable-length re- 
cords. 

DLSRF1 Data mgmt 68 Reserved for PCA1 record format 
Bit Content Meaning 


Reserved 


Records have no keys. 
Records have keys. 
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Table. D—6. .:Contents of Disk. Format 7 Label (Part 3 of 5) 


‘Data mgmt 
Data mgmt 


; Data mamt 


Data mgmt 


Co ad 


DL$DS1 Space mgmt 


DL$KL1. Data mgmt 


Deseri ption 


(Record format, cont) 


Bit Content 


Discontinuous 


Meaning 


Fixed-length blocked 
records 


Variable-length 
blocked records 


Fixed-length un- 
blocked records 


Variable-length 
unblocked records 


Records are inter- 
laced. 


Partition descriptor 2; block size, 


record size, and record format for partition 2. 


Discontinuous ~ 
binary: ~ 


Discontinuous 
binary 


Discontinuous 
binary 


Discontinuous 
binary 


Partition descriptor 3. 
Partition descriptor 4. 
Partition descriptor 5. 


Partition descriptor 6. 


Dats mgmt 94—98 Discontinuous Partition descriptor 7. 
binary 


Data set indicators — reserved for 


future use. 


Key location — high order position 
of key field within each data record 
~ of an indexed-sequential file. 





GO 
f 
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Table D—6. Contents of Disk Format 1 Label (Part 4 of 5) 
y 


DL$SA1 Binary Secondary allocation increment — 
the number of cylinders of disc 
storage to be requested for each 
dynamic extension of the file. 
*“ DL$LH1 103 Hexadecimal — File low head — split cylinder 
allocation. 
DL$HH1 Hexadecimal. File high head — split cylinder 
allocation. 


DL$XxT1 Hexadecimal - Extent type indicator — 
Code Meaning 
00 No valid extent described 
., Sequential file (DTFSD) 
Direct access file (DTFDA) 
Nonindexed file (DT FN!) 
| Indexed sequential file (DTFIS) 
_ IRAM (DTFIR) or MIRAM (DTFMC) 
. SAT (DTFPF) | 
Job Control 


DL$xXS1 Binary Extent sequence number — relative number 
of extents in multiple-extent volume. 
DL$XL1 107-110 Discontinuous Lower limit — the address specifying 
binary the start of the extent, in the 
form CCHH. 
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. Table D—6. Contents of Disk Format 1 Label (Part 5. of 5) 


y 
DL$XU1 woe Hu 1-114 Discontinuous | Upper limit — the address specifying ~ . 
binary the end of the extent, in the form CCHH. 
115— 19k. Second extent — same format as described 
be for bytes.105 through-114. - 


“DLgCP1 — mgmt 135—139- Discontinuous . | Continuation pointer — the address of:a format 
binary 2 label. The address is in the form CCHHA. 





D.3.2. Disk Format 2 Label 


The format 2 label is. used as an extension to the format 1 label to further describe the 
file. 


For nonindexed files (DTFSD, DTFDA, DTFNI), bytes 1 through 43 are used to carry 
partition information in a maximum of seven 6-byte entries. For indexed ISAM files, bytes 
13 through 43 are used to carry index control information. For IRAM and MIRAM files, 
bytes 13 through 43 are. used to carry index control and file characteristic information. For 
library files, bytes 32 through 47 are used to carry information on the aubraky text and 
directory; bytes 13 through 31 contain binary zeros. 


The format 2 label is initialized by space management and maintained by data 
management. The label is always present and. is linked from the format 1 label. The link 
field in the format 2 label will point to a format 3 label, if used. This pointer will be 
present for all split- cylinder files and for nonsplit-cylinder files requiring more than three 
extents. If it is not present, the field is filled with binary zeros. Figure D—9 shows the 
format 2 label; 7 summarizes its contents. The format of the ISAM file 
information area is shown in Figure-D—10, and the contents of this area are listed in 
Table D—8. The format of the IRAM/MIRAM file information area is shown in Figure 
D—11, and the contents of this area are listed in Table D—9. The format of the library file 
information area is shown in Figure D—12, and the contents of this area are listed in 
Table D—10. 
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_ 
4 
| 
i 








BYTES | Q Senses. as So 1 te oe 2 3 
nonindexed LBC key length or lace factor . reserved 
nonindexed LBC. 
key length or lace factor 
(up to five additional partition descriptors) 
reserved ~ blocks/track, PCA1 
i 
PCA1ID relative track addr-1* . 4 tracks 
F if i 2. . 
PCA2ID relative track addr-2* . tracks 
tracks per cylinder . file low head no. 
relative extent count 
: format 3 pointer’ 
*Thirteen bits can represent a maximum relative track address (RTA) of 8191, 9 "1 FFF. 4). To support the larger 8433 
disc, the high-order bit of the tracks field (bit 16) of the egies extent is used U4 inditare that the eae must be increased 
bya ‘constant value of eels (See Table D—7.) 
Figure D—9. Disk Format 2 Label, Nonindexed Files (DTFSD, | _DTFDA, DTFNI) 
es 
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disc address of last prime... 


number of cylinders having 


... data record, plus 1 
overflow space full 


current independent overflow address 


prime data load count be overflow record count 


reserved disc address of last block level ... 


overflow retrieval count, except 


... index record, plus 1 Hist oh ehain 


reserved : total count of prime data records 


bytes of main storage required number of records tagged 
for top index for deletion 


number of blocks per 
cylinder 





Figure D—10. ISAM (DTFIS) File Information Area, Disk Format 2 Label gah 





BYTES 
key location for key 1 . key length for key 1 
used for IRAM processing 
16 ‘key characteristic descriptor for... 
flag byte (MIRAM) 
20 descriptor for... 
24 descriptor for... 
28 . . descriptor for... 
32 sector number of records... 
i offset 
: fine-level index 
36 ..in file, plus 1 record size A, block size in 
sectors 
40 number of index levels : last fine-level index block 
NOTE: ae 


Descriptions that pertain to IRAM files also apply to MIRAM files with IRAM characteristics. 


Figure D—11. IRAM/MIRAM File Information Area, Disk Format 2 Label 
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BYTES 














directory partition lace factor 


32 directory partition lace adjustment factor 


36 text partition lace factor 


40 text partition lace adjustment factor 


44 number of library blocks per track 


NOTE: 


In the format 2 label for library files, byte 3 and bytes 13—27 are reserved and contain binary zero. 


Figure D—12. Library File Information Area, Disk Format 2 Label 


Table D—7. Contents of Disk Format 2 Label (Part 1 of 3) 


by ee 


DL$S1D2 Key identification X‘02’ 


aa a 













initialized 





Nonindexed last block control — the number | 
of logical records in the last block of the 
partition for fixed-length blocked files. 


Key length or lace factor. 


End of data ID — relative block address plus 
1 of the last block written into the partition. 







A 6-byte partition descriptor entry 


in the same form as bytes 1—6. 


Data mgmt 13—43 Hexadecimal For nonindexed files, up to 5 

additional partition descriptors. | 
For ISAM files, see index information 
area (Table D—8 and Figure D—10). 

; For IRAM and MIRAM files, see 

IRAM/MIRAM information area 
(Table D—9 and Figure D—11). 

. For library files, see library information 
area (Table D—10 and Figure D—12). 


Unused (binary zero) for all but indexed files; 
reserved for indexed files. 






















one, 
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Table D—7. Contents of Disk Format 2 Label (Part 2 of 3) 


initialized 
by 


DL$SBPT2 


-DL$SXAR2 Data-mgmt Discontinuous 


binary . 


‘| pustpc2 ee 128-129 |. Hexadecimal 


DL$FLH2 | — .... .| 130-131 


DL$SXCT2 132-133 |, - 


DLESFL2. | 





Description | 


Blocks per-track —-the number of blocks per 
track in the first or only partition of the file. 


-- Logical extent table area— These entries are 


4 bytes in length and specify PCA ID in3 . 
bits, starting relative track address in 13 bits, 
and number of tracks in that.address. . 


From one to twenty 4-byte logical extent — 
entries may be placed in this 80-byte area.) 
Each 4-byte entry has the following format: 


Bit Meaning 


0-2 The high-order three bits of the 
logical extent identify the parti- 
tion to which it is assigned. (This 
value may.be from.-1.to 7.) 


The next 13 bits indicate the relative 
track address of the logical extent. 


If the first bit (bit 16) of the track 
field is set on, a value of 8192 must 
be added to the relative track 

~-address to indicate the relative 
track address of the logical extent 

on the 8433 disc. The remaining 15 
bits indicate the number of-tracks. . 
contained in the extent. 


Tracks per cylinder. for this file. 
File low head — the lowest head . 
number in.the.assigned cylinders | 


accessible for this file. 


Number of relative extents contained _. 


-inthistabel, --5 eS 


Flags. 
Bit Content Meaning 


0 


Reserved 


Library lace adjustment, © 
type2 


Library lace adjustment, — 
type 3 


9400 SAT compatible 


og, 


la 
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- Table‘D—7. Contents of Disk Format 2 Label (Part 3 of 3) 


initialized 
by ... 


Description 


DL$SCID2. Space mgmt 135—139 | . Discontinuous -. The disc address, in the form CCHHR, 
binary of the format 3 label (if required) - 
Pp oes ' associated with this file. 





yoo» 


vr 


Table D—8. Contents of Indexed File Information Area, Disk Format 2 Label 


“Initialized Description 


DL$PID2 | “Data: Discontinuous Disc address of last prime data record (plus 1), 
management binary in the form rrrbb, where rrr = relative block 
ps address and bb = displacement within the 
block 
DL$NMA2) | 22 Hexadecimal Count of cylinders having overflow space 
. filled 
DLSIOF2 
a DL$PDLC2 [| Discontinous Prime data load count 


binary 


DL$NMO2 Data ay " Count of the number of overflow records in 
management * _ the file : 


Reserved 


DL$BID2 nee. =e ; - : 33 : Discontinuous Disc address of last block level index record 
binary (plus 1), in the same form as bytes.13—17 


DL$NMR2 _ i 1 - ~ : Overflow chain retrieval count, not first 
ala | of chain 


Reserved . ; 


_DL$NMP2 | ere ose 37-39 |... Total count of number of prime data records 


DL$NMS2_ Data 40-41 | Number of bytes required to hold top index _|: 
management eS, in main storage 7 


DL$NMT2 | 7 Number of records user has tagged for 
deletion 


Number of blocks per cylinder © 
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Table D—9. Contents of IRAM/MIRAM File.Information Area, Disk Format 2 Label — 


Hexadecimal Used for IRAM file index processing 
(IRAM) 


For MIRAM files, byte 16 contains key 1 
characteristics: 






Description 





















Binary 
(MIRAM) 


Bit Content Meaning 
. O. 1 Duplicates allowed 
for this key 


Key change allowed 
for this key during 
during update 




















Unused 





Index-only records 
permitted in this file 


Variable-length 
record format 














' Record control byte 
(rcb) present 








Discontinuous Descriptor for key 2 (binary ZeTOS for IRAM) 










Descriptor for key 3 (binary zeros for IRAM) 


——oserrerneaae 
[ [ese ay 
2 meen 


a eae Fine-level index block size in sectors 







,OLSCLEV Number of index levels 
_DLSFAB Relative block number of last block of the ~ 
fine-level index 


*These bit positions. are: unused in the descriptors for keys 2 through 5. 
NOTE: 


Descriptions pertaining to IRAM files also apply to MIRAM files with IRAM characteristics. 
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Table D—10.. Contents of Library Information Area, Disk Format 2 Label 


_ Initialized 
juan | toate | aye | cate | § 





Description 










Hardware-adjusted lace factor for the directory 
partition 


DL$DIRL2 | “Data “| 28-31 









management 


DL$DIRF2 | Data 32-35 | 
management 
DL$TXTL2 Data Hardware-adjusted lace factor for the library 
management text partition 
DLSTXTF2 Data ~ | 40—43 Rotational adjustment factor for the library’s 
management text 
Data 44—47 _ Number of library blocks per track 
~ management : i. 


D.3.3. Disk Format 3 Label 


Rotational adjustment for directory lace factor 






The format 3 label is used to maintain extent information for the file. For split-cylinder 
files, a format 3 label is always present. For files not using split-cylinder allocation, a 
format 3 label for the file will exist only when more than three extents are required. 


The format 3 label is initialized and maintained by the disk space management routines. 
The format 3 label, when required, will always be linked from a format 2 label. Figure 
D—13 shows the format 3 label; Table D—11 summarizes its contents. 
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BYTES 
0 oe 
key identification... J mor et oe : 2s st oui! 4 hk 

ce 3 aoe lowerlimit 
8 2 : upper limit’ 
12 

extent 5 
24 

“extent6 
36 

extent 7 coe eGR OR 4 eae : 
44 

f r ae : f 
format 1D 
4a 
ert 
% 
128 
extent 16 
136 
Figure D—13. Disk Format 3 Label 
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Contents. of Disk Format 3: Label 
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Table D—11 

Initialized - - Description 
i. by ee ote i oe 
| DL$ID3 Space mgmt . Hexadecimal . Key: identification — each byte 
See) contains 03 
DL$XT3 Hexadecimal Extent type indicator — 
Code Meaning 
_00 © No valid extent phyla 
Oe. "Prime oe area 
. DLSSN3- Extent sequence ntimbers — - relative 
number of extents in this volume of 
the file. 
Discontinuous Lower limit — starting track address 

"binary, re of the extent, in the form CCHH. 


Extent 5 — same tonnes as stcribed 


DL$XL3 
for bytes 4 through 13 for this 
extent. 


Format idenciie — always 3, a 


~ format 3 label. 
Extents 8 through 16 


Pointer, — address of next format 3 
label, in the form CCHHA. Binary 0 


ae skeee 
DL$CP3 Discontinuous. | :P 
~ 3. «|. Jfno further label. 


=ECBIC: 
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D.4. OPTIONAL USER STANDARD LABELS 


Optional user standard labels are records made available to you via your label processing 
routine (LABADDR) at the opening or closing of a disk volume. OS/3 data management 
supports user standard: labels for your SAM and DAM disk files described by the DTFSD, 
DTFNI, and DTFDA declarative macroinstructions; it does not support them for your ISAM 
files, which are described by the DTFIS macro. | 


D.4.1. User Header Labels: 


lf you require user header labels, these will be written on the first track of each volume of 
a DTFSD file and on the first track of the first volume of a DTFDA or DTFNI file. You may 
write a maximum of eight labels. Figure D—14 shows the format of the 80-byte user 
header label; its contents are explained in the table below Figure D—14. 


0 eee ee: | 2 | 3 









label ID 


label data: - 


76 





Field Bytes Code Description 





Label 1D 0-3 ~EBCDIC_ ~ Contains 4-byte label 
pa ‘identifier: UHL, followed 
by a label number which 
“ranges from 1 through 8. 


Label data 4—79 User option Contains 76 bytes of user 
specified header label data. 


Figure D—14. Optional User Standard Header Label 


P - 
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D.4.2. User Trailer Labels 


lf you need user trailer labels, these will be written on the first track of each volume of.a 
DTFSD file and on the first track of the first volume of DTFDA or DTFNI files, following 
your user header labels. You may write a maximum of eight labels on DTFDA and DTFNI 
files, and eight labels per volume on DTFSD files. Figure D—15 shows the format of the 
80-byte user trailer label; its contents are explained in the table below Figure D—15. 






label 1D 
4 

label data 
76 





Field Bytes Code " Description 








“Label ID 0-3 EBCDIC Contains 4-byte label 
o* identifier: UTL, 
followed by a label 
‘number which ranges 
from 1 through 8. 


Label data 4-79 User option Contains 76 bytes 
; of user-specified 
trailer label data 


Figure D—15. Optional User Standard Trailer Label 
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D.5. 8413 DISKETTE FILE LABEL 


‘Figure D—16 ‘illustrates the 8413 diskette file label form 


contents of each field in the diskette file label. . . on 
Pee be, a — Sens Oi Pee G : a : 


12 


20 
24 
28 

32 


36 


40 


48 
52 
56 
60 
64 
68 
72 
76 


80 


124 









- reserved 


_ file identifier 






not used 


block length record attribute 






beginning of extent (BOE) 


physical record aes 
length . 










we 


ar) 3 


record/block format 


exchange type ind. 












bypass ind. 


ees ey 


record length 









: ar 


~ not used 


reserved 
reserved 


file expiration date 


end of data (EOD) 


















reserved 


Figure D—16. 8413 Diskette File Label Format 


at. Table D—-12' explains the 


label ID 
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Field 


label ID 








Reserved 


File identifier ° 






Block length - 


Beginning of extent (BOE) 









‘Physical record length ~ 


Record/block format: :-::. 





Bypass indicator’. .» 












File security 





Write protect 


Multivolume indicator 


Volume sequence number 


File creation date 








-| ... Byte Position 


‘End of extent (EOE): 


| 
Exchange type indicator 4 
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= Table D—12.-- Diskette File Label Description (Part 1of 2) 

















‘Description 
Contains '4-byte label identifier HDR followed by the Number 1... 
: Reserved 
- Names. user file and is from 1 to 8 characters. First character must — 
‘be alphabetic -and-no blanks are allowed. Duplicate-names on the _ 
same diskette are not allowed.” - oe : es 
Not used 
Indicates the record size as follows: 


Character Meaning 


A Record size will be obtained from the DTF 











1—128 - Actual record size; for example, 80. - 


pa 


Blank; indicates unblocked records 


Identifies the ‘address of the first sector of the file by cylinder 
number (pos. 28—29), head (pos. 30), and sector number (pos. 
31—32). 







~ Indicates physical record length and is blank meaning 128 bytes per - 
“. record. 8a pares | a 


« . Indicates address of last sector. reserved for this-file and uses the 
same format as BOE. : 









*~ This field must be blank. 


' 4ndicates a file to be skipped during, exchange or copy operations 
--'when transmitting or transferring files on the volume. If position 40 
is blank, the file is transferred; if B, the file is not transferred. 


Blank indicates the file can be accessed. Nonblank indicates 
restricted access. When nonblank, the’voltinie accessibility indicator » 
in: the volume label (track 00, sector 07) must also be nonblank. 

















Blank indicates both reading. and writing allowed. P indicates only , 


read activities allowed. ~ “ 


Blank indicates file can be used for basic exchange. Nonblank 
indicates additional label checking is needed to exchange the file: <. 


3 
44 Character Meaning 










blank File on 1 diskette 





File continued on next diskette 





Cc 


Last diskette on which file resides 





L 








Indicates volume sequence number in multivolume set (01—99). 
Blanks indicate no volume sequence checking performed on this 
device. 





Indicates the creation date of the file by year (YY), month (MM), and 
day (DD). Blanks indicate nonsignificance of creation date. 
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Table D-—-12. Diskette File Label Description (Part 2 of 2) 


_| ‘Byte Position ee Description — a 


Record length penheg 6 . Defines record length. 





Sipb = ‘record length equals block length (position 22) 
(This field is ignored because blank in position 43 means.the same.) 
Offset to next record space so. sf Not used 


File expiration date »s - Contains date of deletion for a. file. (Format is the same as creation | 
date in position 47—52.) 





Spb bbb = file date expired 
999999 = file date never expires 
“1 Verify/copy indicator : Character Meaning 
| Spank | File is created 
Vos. File is verified 
Cc | ’ File data’ successfully transferred to another medium ~* 
: File erannieariog | ; | If position 43 contains blank; this ues must also contain blanks. | 


‘End of data (EOD) - , . - Identifies address of next unused sector within. the file extent using 
; BOE ney 


If FOG equals BOE. the extent contains a- nul file. 


If: EOD: equals address ot next = piece: edad: file -extent 
(unblocked records), entire extent was used. 


If blocked records are“used, EOD must be used with offset to 
. Next record space (position 57—61) to find the actual EOD. 


Reserved. : ge SEN Te ia a - Reserved 





Padded with binary zeros 
“NOTE: dot be Sie eseen es 


‘ISAM does not support the 8413 diskette. 


OR 


ali 
‘ 
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| Appendix E. Magnetic T ape Labels 


E:1.. OS/3. shdtali STANDARD LABELS FOR: MAGNET TAPE 


This appendix deceribes the system Siandara: labels for imaonetie tape flee and feale (or 
volumes). in OS/3. Section 8. describes magnetic tape SAM record formats, volume 
organization, and file conventions. Section 9 describes the functions and operations. of 
magnetic tape SAM, including certain of the label-processing functions of: transients 
entered by the OPEN and CLOSE imperative macros and the user’s own special label 
processing routine (the address of which he provides to tape SAM. by specifying the 
LABADDR keyword: parameter in the DTFMT declarative macro defining any standard 
labeled magnetic tape file for which optional standard user header or trailer labels (UHL or 
UTL) are to be processed). The LBRET imperative macro (9.4. Sh is i! in the user's label 
routine to control returns to and from tape.SAM. - : = beats 


In 0s/3 tape SAM, magnetic Hobs may be “iebeledie or unlabeled: ana a labeled (ape. may 
contain either.nonstandard or OS/3 system standard labels. Tape volumes. have formats 
that may be specified as standard, nonstandard, or unlabeled, using the .FILABL keyword of 
the DTFMT declarative macro (9.2.6.1); . unlabeled format is pesuimed if. this meyers is not 
specified. Ur : 


E.2. SYSTEM STANDARD TAPE LABELS | 


All standard tape labels, neluding optional UHL and UTL,. are in blocks of 80 bytes. There 
are five tape. label. groups: three. Npauires ‘two. optional: 


. Volume label group | 

: File header label group 

m User header label group enone 
: | File trailer label group | | 


= User trailer label group (optional) 
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E.2.1. Volume Label Group 


The volume label group comprises a single volume label, VOL1. The VOL1 label identifies 
the.tape _ reel. and its owner, and it is used to check that the proper reel is mounted. (Refer 
to Table 9—3). When a tape is first used at an installation, its volume serial number (VSN) 
and other volume information, as shown in Figure E—1, are usually recorded on it 
magnetically with the TPREP utility routine, being specified to the routine with parameter 
cards. The volume serial number is also written on the exterior of the reel for visual 
identification to the operator. For a detailed description of TPREP, refer to the system 
service programs (SSP) user guide, UP-8062 (current version); note that you cannot use 
this routine to prep a magnetic tape volume dynamically, although you may prep as many 
as 36 volumes with it. 


As an alternative to using TPREP, if you want tape SAM to prep the volumes. of a:standard 
labeled file dynamically, as a preliminary part of the job step in which you create the file, 
you’ specify the parameter. (PREP) in the: VOL job control statement of the file’s device 
assignment set, also specifying a.unique VSN: Data management then preps the .volumes 
from information you supply on the: associated VOL and: LBL statements. De si proceeuie is 
GeSoribed in 1 23. 3. 3. BOS ee Ps pene 


When you issue an OPEN macro to an “OUEBUEt tape file, its open- “arial: Kewind eptions: are 


executed first (9.2.5.2 and 9.2.5.3), and then the tape is checked:to‘see ‘if itis at-the load 


point. a it is: at the load pert data: menegenient reads ‘the VOL1 label (if it is not in: the 
labels (HDR1 and HDR2). It then positions your tape so that the. volurietabels” are not 
calle ba and no CUTS von dabel pocessing is eee 

if the durpat’ tae | is not at the ‘6a patrt after the open- ae rewind: ‘options are peuecited 
tape SAM ‘assumes that it is positioned between the two ending: tape marks .of the 
previous filé; or-just prior to the HDR1 label ofan existing file. In either case, no volume 
label checking or creation is performed. : 


For an input tape, the OPEN transient first executes the open-and-rewind options and then 
checks to see whether the tape is at the load point. If itis, the VOL1 label is read and the 
VSN is used to check the file serial number in the appropriate file header or trailer label. 
The tape is then positioned to the proper file header or trailer label, as specified in the file 
sequence number field of the associated LBL job’control statement (9.3.4), ‘and no further 
volume label processing is performed. If the input tape is not at the load point after your 
open-and-rewind options are executed, tape SAM assumes that the tape is: positioned 
between the two ending tape marks of a previously created file, or just prior to the HDR1 
label of an existing file. In either case, no further volume label processing is performed. 


When any volume label is encountered during the processing of a CLOSE macroinstruction 
for an input tape (9.2.5.4, 9.4.2), if you have specified READ=BACK (9.2.5.1), the label is 
bypassed without processing. Figure E—1 shows the format of the VOL1 label; its fields 
are described in Table E—1. 


BE SUC R Hava SPERRY UNIVAC 0S/3 B-3of ae 
BASIC DATA MANAGEMENT 








volume serial number 
reserved 
reserved 
- reserved 
ons, 
a oat 
reserved 
LEGEND: 
WS ; 
NS Generated by data management or reserved for system expansion. 
Written by data management from user-supplied data. 
ee ~ 


Figure E—1, Tape Volume 71 (VOL1) Label Format for an EBCDIC Volume 
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Table E—1. Tape Volume 1 (VOL1) Label Format, Field Description for an EBCDIC Volume 


fee cee | prep ere | | Contains "VOL" to indicate 
fee that this is a volume label 


ae - Label number Tape prep EBCDIC Always “1”, for the initial 
: volume label . 


| Volume serial Tape | prep EBCDIC 
‘| number 
FEE - 


a 31—40 | eBcDIC Contains blanks mae 


Tape prep — EBCDIC Unique identification of the 


owner of the reel: any 
ee eee 51-79 | EBcDIC Contains blanks (40, «) 


combination of alphanumerics 
E.2.2. File Header Label Group 

























Unique identification number 
assigned to this volume by 
your installation. Tape SAM 
expects 1 to 6. alphanumeric 
characters, the first of which 
is alphabetic 













Reserved for future use by 
installations requiring 
security at the reel level. 
Currently blank © 






. Molume 
‘| security 





















Owner 
identification 

















The file Reader label group comprises two labels, HDR1 and HDR2, described in the 
following subparagraphs. 


E.2.2.1. First File Header Label (HDR1) 


The first file header label (HDR1), which identifies the file, is written at the beginning of 
each file. The HDR1 label is required and has the fixed format shown in Figure E—2; its 
fields are described in Table =e All fields in the en ane! may be specified in the job 
control stream. 
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file identifier 


12 
16 
20 


file serial number 


24 - : volume. . . 


28 ... sequence number 
32 ... sequence number - generation... 
36 ... number version. .. 


40 . ... Number 


ae _ creation date 


( 


48 a _ expiration date 
52 
56 . . unused 
60 
64 | system-code 
68 
72 


reserved 
76 





LEGEND: 
Generated by data management or reserved for system expansion. 


Written by data management from user-supplied data. 





Figure E—2. First File Header Label (HDR1) Format for an EBCDIC Tape Volume 
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Table E—2. First File Header Label (HDR1), Field Description 


rans a | yeas | _ Description 
Label identifier + Contains “HDR” to indicate a file header label 7 
Label number fee 4 Always 1" “ 


File identifier 4—20 A 17-byte configuration that uniquely identifies 
* the file-it may contain embedded blanks and is 
left-justified in the field if fewer than 17 bytes 
are specified. 


File serial number 21—26 The same as the VSN of the VOL1 label for the 
eee first reel of a file or a group of multifile reels 
Volume sequence The position of the current reel with respect 


number ~ to the first reel on which the file begins. 


. File sequence number 1 — | The position. of this file with respect to the. 
first file in the group. 


Generation number — 38° | The generation number of the file (0000—9999) 


if m ; . : = " 
--MVersion number of ~~ - - The version number of a particular generation 
generation 


"> Creation date The date on which the file was created, expressed 
in the form YYDDD and Ig CAustitied: ‘The 
- leftmost position is blank. 


Expiration date -52. | . The date the file may be written over or used 


_as scratch, in the same form as the creation 


File security indicator Reserved for file security indicator. Indicates 
whether additional. qualifications must be met 
before a user program may have access to the file. 


O=No additional qualifications are required: - 


1 = Additional qualifications are required. 


I System code 60-72 | Reserved for system code, the unique identification 
— of the operating system that produced the file 


oe Reserved 
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For input tapes, all fields up to and including the system code field in the HDR1 label are 
checked at file open against the values you specify in the LBL job control statement 
(9.3.4), unless you have specified read-backward processing (9.2.5.1). If you have specified 
READ=BACK, tape SAM bypasses the HDR1 label without processing it. For multifile input 
volumes, you should specify the file sequence number in the LBL ; 40p control ‘statement to 
ensure proper tape positioning. , 


For output files, the tape must be positioned properly before you may open the files. On 
file open, the expiration date in the HDR1 label. is. checked. against the current or actual 
calendar date to determine whether the associated file has expired. If it has not, data 
management issues error message DM57, and it is not-possible to write. to the file. You 
should mount the correct volume and rerun. 


If the file Has expired, the tape is positioned so that the old HDR11 label is overwritten. The 
HDR1 label for the new file, set up from the values you specify in the LBL job control 
statement, is written on the tape. ‘ 


E.2.2.2. Second File Header Label (HDR2) 


The second file header label (HDR2) acts as an extension of the HDR1. label and is 
required in standard labeled files. Unless the HDR2 label was created by OS/3, however, 
as indicated in the system code field of the HDR1 label, tape SAM ignores the HDR2 label 
on input tapes. Figure E—3 shows the format of the HDR2 label; Table ae describes its . 
fields. ae 
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record format 


character block length 


record length ° 


-. reserved 


reserved 





LEGEND: 


WN Generated by data management or reserved for system expansion. 





Written by data management from user-supplied data. 


Figure E—3. Second File Header Label (HDR2) Format for an EBCDIC Tape Volume 


pre, 
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Table E—3. Second File Header Label (HDR2), Field Description 


Meaning 


Variable-length, with length 
fields specified in decimal 
Fixed-length 

Undefined 

Variable-length, with length 
fields specified in binary 


Five EBCDIC characters specifying the record length for. 
fixed-length records. For any other record format, this 
field contains O's. 





Reserved... 


E.2.3. File Trailer Label Group 


The file trailer label group comprises either of two pairs of labels, depending on whether 
the reel contains an end-of-file or an end-of-volume..condition. In the first condition, the 
first label of the pair is the EOF1 label, in a format identical to the HDR1 label; the second 
label is the EOF2 label. Its format is identical to the HDR2 label. In the end-of-volume 
condition, these labels are the EOV1 and EOV2 labels; again, the formats of these labels 
are identical to their counterparts in the file header label group, HDR1 and HDR2. 


When you issue an OPEN macroinstruction to an input tape file, with READ=BACK 
specified in the DTFMT macroinstruction, the OPEN transient checks the fields in an EOF1 
and EOV1 label against the values you have specified in the LBL job control statement. 
This processing is similar to that of the HDR1 label. . 


Figure E—4 illustrates the format of the EOF1 or EOV1 label; Table E—4 summarizes the 
contents of its fields. Similarly, Figure E—5 and Table E—5 describe the EOF2 or EOV2 
label. 
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BYTES ea oe ee e 5geevalaney © aise, ENS f 
4 
label identifier label 
abel identifier 
Det haerys number . 
file identifier 
¥ 
file serial number z: 
; volume... 
i. .sequence number 
. ..sequence number - ‘|. generation... 
...number -- Bee Capa bes? ths, version. .. 
...number 
creation date Ss Pa 
= 3 4 
Shae 


expiration date 


block ‘count - 


system code 


reserved 





LEGEND: 
Generated by data management or reserved for system expansion 


Written by data management from user-supplied data 


Figure E—4. Tape File EOF1 and EOV1 Label Formats 
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Table E—4. Tape File EOF1 and EOV?1 Labels, Field Description 


Description 


: : Label identifier Indicates that this is a file trailer label; 
tare Savi «alk contains ‘‘EOF” for an end-of-file label, . 
or:“EOV" for an end-of-volume label 


~ Label number | Always "1" — 7 


File identifier “A 17-byte configuration that uniquely identifies 
the file. it may contain embedded blanks and is 
left-justified in the field if fewer than 17 __ 


bytes are specified. 


The same as the VSN of the VOL1 label 
for the first reel of a file or a group of 
multifile reels 


File serial number 


_The position of the current ree! with respect 


~ Volume sequence number 
a to the first reel on which the file begins. 


. File sequence number The position of this file with respect to the - 


first file in the group 
. Generation number 35-38 The generation number of the file (0000-9999) 
The version number of a particular generation 


Version number of 
» generation 


of a file a: 


most position is blank. 


The date the file may be written over or used as 
scratch, in the same form as the creation date - 


ee Expiration date 


Reserved for file security indicator. Indicates 
whether additional qualifications must be met before 
a user program may have access to the file. — 


File security indicator 


0 = No additional qualifications are. required. 
1 = Additional qualifications are required. 


In the first file trailer label, indicates the 
number of data blocks: either in this file of 
a multifile reel, or on the current reel of a 
multivolume file. Tape SAM checks the block 
count for input files or writes the count for, 


Block count 


' Creation date The date on which the file was created, expressed 7 
é in the form YYDDD and right-justified. The left- 


‘output files. 


System code 60—72 Reserved for system code, the unique identification 
of the operating system that produced the file» - .: 
,. 73-79... Reserved field, containing blanks (40). ey 
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BYTES 


0 : - label identifier - label \ 
: zie : number 

record format 

character 


block length 


12 record ljength 
16 
20 
24 | 
reserved 
28 
| 32 
36 
40 
44 
48 
52 | 
. reserved 

56 
60 
64 
68 | 


72 


76 





LEGEND: 


WN Generated by data management or reserved for system expansion. 





Written by data management from user-supplied data. 


Figure E—5. Tape File EOF2 and EOV2 Label Formats 





oon 


ee 
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Table E—5. Tape File EOF2 and EOV2 Labels, Field Description’ 








Description 





ifgicates that this i is a file trailer label; contains 
“EOF” for an end-of-file label, or “EOV” for 
an end-of-volume label ; 


‘Label identifier 












Record format character Character ' Meaning © 


. Mariable-length, with length 
fields specified in decimal 









F Fixed-length 
U Undefined 
Vv Variable-length, with 









length fields specified in binary 


Five EBCDIC characters specifying the maximum 
number of characters per block ; 


Five EBCDIC characters specifying the Tecate d length 
for fixed-length records. For any other record 
format, this field contains 0's. 


36-79 Reserved for future system use ; 






Block length 






Record length 
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E.2.4. Standard User Header and Trailer Labels. 
In a standard labeled file, you may use only-the standard UHL and UTL; within the OS/3 

tape SAME conventions, their use is entirely optional. You may have one or as many as 

eight UHL, or none at all; the same applies to optional UTL. If you use them, they must be 

in the OS/3 standard 80-byte format and content as described in Figure E—6 and Table 

E—6. Their position in a standard labeled tape volume is as prescribed in Section 8. 


When you have specified the block numbering option with the BKNO keyword parameter 
of your DTFMT declarative macro (9.2.3.5), the system labels and your optional user labels 
may not be the standard length. Optional user labels in an EBCDIC input file must then be 


83 bytes long, and user labels in an ASCII input file 81 bytes long, to ensure correct 
processing. ae 


BYTES 


a a oan WS 
label identifier label SS 


number. 


2° 


label data 


ate 


ai 





LEGEND: 
Written by user’s LABADDR routine. 


SS 
Written by data management. (See note to Table E—6.) 


Figure E—6. Optional User Header and Trailer Label Format, ASCII and Standard Labeled EBCDIC Tape Files 


Table E—6. Optional User Header and Trailer Labels, Field Description for Standard Labeled Tape Files 


a 


Label identifier 0-2 








Contains ‘“‘UHL" for user header label; ““UTL” for 
user trailer label 


Label number Ranges from 1 through 8 (See note.) 
Label data Contains 76 bytes of user-specified information 


NOTE: 










For ASCIl files, the label number is not written by data management; it is the user’s responsibility. Also there is 
no limit on the range; the user may have any number of user labels he wants. 


0S/3 magnetic tape SAM writes and ‘processes. ‘the following’ ASCII standard: labels: 
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E.3. ASCII STANDARD MAGNETIC TAPE LABELS 


~The figures and tables that follow describe the labels written (and expected to be read) by 
08/3 magnetic’ tape SAM for ASCII files. Note the very small differences. for foregoing 
- EBCDIC labels and these ASCII labels; which conform to American. National: Standard 
Magnetic Tape Labels for a aL alah fee EaTge x3. 27 - — 7 969. ee cs 


& 


VOL1, HDR1, HDR2, EOV1, EOV2, EOF1, and EOF2. Although data management also 
provides. for input and output processing of optional UHLs and UTLs (their forms are 


i; identical in ASCII to those described in E.2.4), it does’ not provide for processing optional 
“user volume labels (UVLs) on’ output. If present on ASCII input tapes, UVLs are secepict 


but bypassed and ignored. 


For ASCII record formats and reel organizations, refer to Section 8. 


pe 3. 1. ASCII Character Code and Processing 


: During’ input and output processing of ASCII magnetic: fape: files, 0s/3 data management 
uses the: character ‘code specified by American National Standard:Code for Information 


Interchange, X3.4 —-1968, performing appropriate translations (EBCDIC to ASCII, or vice 
versa) so that your program always processes in EBCDIC. Refer to 9.2.7.1 for details on 
specific or automatic inclusion of the OS/3 ASCII translation table module during link 
time. Appendix C provides a useful cross-reference table dépicting the correspondence 


between ASCll and eae 


E. 3.1. 7 oe Output Processing 0 of Labels in ASCII Magnetic Tape Files - 


When you specify ASCII = YES in the DTEMT declarative macro defining an output 
magnetic tape file, OS/3 data management writes out all system labels in ASCII. Just as 
you must present your ‘data to data management in EBCDIC (9.2.7.1) so also must you 
present your optional UHL and UTL label data in EBCDIC. Data management translates 
these into ASCII before writing them out to tape: It is al mt eeponetn ity to write out the 
label number. 


E.3.1.2. Input Processing of Labels in ASCII Magnetic Tape Files 


“When reading input’ magnetic tape files coded in-ASCII, OS/3 data management assumes 


that these comply fully with American National Standard X3.27 — 1969, and that there is 
no mixture of character codes. Any exception may result in incorrect processing. Before 
passing your data and your optional UHLs or UTLs to you, data management translates 
these into the form it expects to receive before ouptut: your program receives data and 
labels in EBCDIC. 


ae 3, 2. OS/ 3 Processing of Certain Fields in ASCII I Tape Labels 


The format and content of ASCII magnetic tape labels in OS/3 are depicted’i in Figures 


E—7 through E—11 -and Table E—7 through E—11. These subparagraphs describe the 
way OS/3 processes certain of the label fields; further notes appear in the tables. 
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E.3.2.1. Accessibility Field 


The accessibility field occurs in the VOL1, HDR1, EOF1, and EOV1 labels. During read- 
forward input, a ‘‘space” (2/0) encountered: in this field of both the VOL1 and HDR1 labels 

_ allows processing to continue, whereas a nonspace in either field causes the issuance of 
error message DM12 to the operator’s console; processing may not continue unless the 
operator responds with the override option in effect at your installation. (For backward- 
_tead input, the procedure is daennicaly ne fields p Intantog ated pein those in the EOV1 and 
EOF1. labels.) — 


. In 0S/3, there is no option to write a nonspace character in the accessibility field of any 
system label on output ASCII tapes; data management. always creates this field as 
“space”. : 


E.3.2.2. Label Standard Level Field 


The /abel standard level field occurs only in the VOL1 label. When writing output ASCII 

tapes, data management writes ‘“1’’ in this field to indicate that the tape is in full 

compliance with American National Standard X3.27 — 1969. On input tapes, a ‘’1.””.in this 

field ensures correct processing; tapes created under later versions of the standard may 
- also be accepted, but you cannot be assured. _of correct processing. . 


E.3.2.3. ie Date Field a a - ee | 7 ; 7 i : is Po 


The expiration date field occurs in the HDR1, EOF1, and EOV1 labels. If you attempt to 
write over an unexpired file in an ASCII tape (one whose expiration date is later than 
today’s date), data management issues error message DM5/7 to the operator console. You 
will not be able to continue processing unless the SPeretOr responds with the override 
Spren in effect at your installation. : 


You should note that, ina “mulitile ASCII volume, if you give a file a /ater expiration date 
than you have given to the files that you have already recorded on the tape, this additional 

protection you intend is not effective. The expiration date of the first file on a volume is 

the latest date on which any part of the volume is protected from being overwritten. 


E.3.2.4. System Code 


In writing output tapes, data management writes ““OS3”, left-justified in the 13-byte 
system code field. The remainder of the-field is filled with “spaces”. The field is ignored on 
input. or _ . 


E.4. PADDING 


In other systems, provision has sometimes been made to allow label blocks to be extended 
in length to the nearest multiple of the computer's word length, any desired characters 
being used for padding. OS/3 does not provide for padding of labels (nor of data blocks: 
see Section 8). If the labels in your ASCII input files are not exactly 80 bytes in length, 
they cannot be processed properly by OS/3. (If BKNO=YES is specified, however, label 
length should be exactly 83 bytes.) | _ | 
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BYTE 


volume serial 
umber Bf 
nan accessibility 


reserved for future 
standardization 


reserved for future standardization 


% 


Rae 


owner identification 


reserved for future 
standardization 


label standard 
} level 


Me Figure E—7. Volume Header Label (VOL1) for an ASCII Magnetic Tape Volume 
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Table E—7. Volume Reger Label (VOL1), Field Description for an ASCII Volume 





Label: identifier 


Volume serial number 


Accessibility 


. Reserved 


Owner identification 


Reserved 


Label standard level 





‘Must be "VOL" 
Must be "1" 


Six ‘‘a’”’ characters -seemnanantly assigned by the owner to 
eae this. physical volume (that is,.this reel of Magnetic a 
tape). (See Note 1.) 


An “a” character that indicates any restrictions on who 
may have access to the information in this volume. A 
“space” means unlimited access; any other character 
means special handling, in the manner agreed upon 
between the interchange parties. (See Notes 1 and 2.) 


& 


Reserved for future standardization. Must be “'spaces’ - 
(See Note 2.) 

Reserved for future standardization. Must be ‘‘spaces’’. 
(See Note 2.) 


Ma ” 


Any “‘a” characters, identifying the owner of the physical 


_ volume (See Note 1.) 


Reserved for future standardization. Must. be ‘‘spaces” 
(See Note 2.) 


“1"' means that the labels and data formats on this volume - f 
conform to the requirements of American National oe 
Standard X3.27—1969. ‘‘Space’’ means that the labels 

and data formats on this volume require the agreement 


of the interchange parties. (See Note 2.) 


NOTES: 

1 An “‘a” character is any of the characters occupying the center four columns of ASCII (American National Standard Code for 
ape Interchange) except position 5/15 and those positions where there is a provision for alternative graphic 
representation. 

2. “Space” is the normally nonprinting graphic character occupying position 2/0 of ASCII. 
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BYTE. 
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|. file identifier... 


set identification 


.. . Section number 
-... Sequence number 


ation number : generation... 


... version number 


: 


creation date 


expiration date 


accessibility 


block count 


~ = system code 


reserved for future 
standardization 
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Table E—8. First File Header Label (HDR1), Field Description for an ASCII Volume (Part 1 of 2) 


a 
a 
Any 


File identifier a 
























characters agreed on between originator and 
recipient . (See Note 1.) 


"9 we 


Set identification Any characters to identify the set of files of which 
this is one. This identification must be the same for all 


files of a multifile set. (See Note 1.) 





The file section number of the first header label of each 
file is “0001"'. This applies both to the first or only file 
on a volume and to subsequent files on a multifile 
volume. This field is incremented by one on each 
subsequent volume of the file. 


File section number 





























File sequence number Four ‘’n” characters denoting the sequence (that is, 


0001, 0002, etc) of files within the volume or set of 
volumes, In all the labels for a given file, this field will 
contain the same number. (See Note 3.) 








Generation number (optional) Four “’n” characters denoting the current stage in the 


succession of one file generation by the next. When a 
file is first created, its generation number is 0001. (See 
Notes 3 and 4.) 





“"n ae 


Two characters distinguishing successive iterations 
of the same generation. The generation version number 
of the first attempt to ee a file is OO. (See Notes 

3 and 4.) 


Generation version number (optional) 








Creation date A “space”’ followed by two “‘n” characters for the year, 


followed by three “’n” characters for the day (001 to 
' 366) within the year (See Notes 2 and 3.) 














Expiration date Same format as creation date field. This file is regarded 
as “expired” when today’s date is equal to, or later than, 
the date given in this field. When this condition is 

satisfied, the remainder of this volume may be overwritten. 
To be effective on multifile volumes, therefore, the 
expiration date of a file must be less than, or equal to, the 
expiration date of all previous files on the volume. 









Accessibility 





An “a” character that indicates any restrictions on who 
may have access to the information in this file. A ‘’space”’ 
means unlimited access; any other character means special 
handling, ina manner agreed upon between the interchange 
parties. 


Block count | sas Must be “‘zeros”’ 


System code (optional) 


Reserved 


NOTES: 





















Thirteen ‘‘a” characters identifying the operating system 
that recorded this file. Output tapes written by OS/3 
tape SAM contain “OS3”. 


73-79 Reserved for future standardization; must contain “‘spaces” 


1. An “‘a" character is any of the characters occupying the center four columns of ASCII (depicted in American National Standard 
X3.4— 1968), except for position 5/15 and those positions where there is provision for alternative graphic representation. 








e 


aan 
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Table E—8. First File Header Label (HDR1), Field Description for an ASCII Volume (Part 2 of 2) 


2. A “space’’ is the normally nonprinting graphic character occupying position 2/0 in ASCII. 
3. An “n” character is any ASCII numeric digit, from 0 through 9. 
4, “‘Optional,”” when used to describe a field in these ASCII labels, means that the field may, but need not, contain the information 


described. If an optional field-does not contain the designated information, it must contain “spaces”. 


BYTE 






block length 





24 reserved for operating systems 





28 
32 
36 


40 


buffer offset 





52 


56 






reserved for future 


60 standardization 





72 


76 


Figure E—9. Second File Header Label (HDR2) for an ASCII Volume 
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Table E—9._ Second. File Header Label (HDR2), Field Description for an ASCII Volume 


Description © 


Label identifier 


Label number 


Record format Meaning 


Fixed length 


Variable, with the number of characters 
in the record specified in decimal 


Variable, with the number of characters 
specified in binary. (See Note.): 


Undefined 
Block length — : Five ‘’n”’ characters specifying the maximum number of 
characters per block. (See Note 3, Table E—8.) 


Record length: Five ‘’n”’ characters specifying: if ‘‘record format” is F, 
record length; if D or V, maximum record length including 
any count fields; if U, then undefined. (See Note.) 


15-49. - ae Reserved for OS/3 use; currently “‘spaces”’ gt 


Buffer offset (optional) 50—51 Two ‘‘n” characters specifying the length in characters of 
: any additional field inserted before a data block—for 
example, block length. This length is included in the block 
length. (See Notes 3 and 4, Table E—8.) 


Reserved 52—79 Reserved for future standardization; must contain ‘‘spaces’’. 
(See Note 2, Table E—8.) 4 


NOTE: 


TP 





OS/3 magnetic tape SAM does not support the ASCII ‘’V-format” record. - 
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-s fabel identifier 


file identifier 


set identification 


*.. « section number 


. ». sequence number 
~ . ation number 


... version number. 


_+_ creation date 
. expiration date 


"accessibility 


block count 


'-/ system code 


reserved for future: 
standardization — 





"> Figure E—10. First End-of-File or End-of-Volume Label (EOF1/EOV1) for an ASCII Volume __ 
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Table E—10. First End-of-File or End-of-Volume Label (EOF1/EOV1), Field Description for an ASCII! Volume 


Label identifier 0-2 Contains “EOF” if an end-of-file label; “EOV’”’ for end-of- 
volume label 


File identifier Any “‘a’’ characters agreed on between originator and 
recipient (See Note 1, Table E—8.) 





Set identification Any “‘a” characters to identify the set of files of which 
this is one. This identification must be the same for all 
files of a multifile set. (See Note 1, Table E—8.) 


File section number The file section number of the first header label of each 
file is ““0001"’. This applies both to the first or only file © 
on a volume and to subsequent files on a multifile | 
volume. This field is incremented by one on each 
subsequent volume of the file. 


File sequence number _ Four “‘n” characters denoting the sequence (that is, 
0001, 0002, etc) of files within the volume or set of 
volumes. In all the labels for a given file, this field will 
contain the same number. (See Note 3, Table E—8.) 


Generation number (optional) _ Four ‘‘n” characters denoting the current stage in the 
i : succession of one file generation by the next. When a 

file is first created, its generation number is 0001. —- 

(See Notes 3 and 4, Table E—8.) 


pom, 


| Generation version number (optional) Two “‘n” characters distinguishing successive iterations 
of the same generation. The generation version number 
of the first attempt to produce a file is 00. (See Notes 
3and 4, Table-E—8.) 
Creation date A “‘space’’ followed by two ‘'n” characters for the year, 
a te ° ; followed by three ’‘n” characters for the day (001 to 366) 
within the year. (See Notes 2 and 3, Table E—8.) 


Expiration date Same format as creation date field. This file is regarded 

. as ‘‘expired’’ when today’s date is equal to, or later than, 
the date given in this field. When this condition is 
satisfied, the remainder of this volume may be 
overwritten. To be effective on multifile volumes, 
therefore, the expiration date of a file must be less than, 
or equal to, the expiration date of all previous files on 
the volume. 


Accessibility An “a” character that indicates any restrictions on who 
may have access to the information in this file, A “’space”’ 
means unlimited access; any other character means special 
handling, in a manner agreed upon between the interchange 
parties. (See Notes 1 and 2, Table E—8.) 


Block count 
System code (optional): ‘Thirteen ‘‘a’”’ characters identifying the operating 


system that recorded this file. Output tapes written by 
OS/3 tape SAM contain “OS3"’. (See Note 1, Table E—8.) 


Reserved 73-79 Reserved for future standardization; must be ‘spaces’. 
(See Note 3, Table E—8.) 
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label identifier 


block length 


record 
length 


_ reserved for operating 
- systems 


buffer offset 


reserved for future 
standardization 





Second End-of-File or End-of-Volume Label (EOF2/EOV2) for an ASCII Volume 
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Table E—11. Second End-of-File or End-of-Volume Label (EOF2/EOV2), Field Description for an ASCII Volume ~ 


Label identifier ! Contains “EOF” if an end-of-file label; “EOV” for end- 
of-volume 


~ Record format Character Meaning 
F Fixed length 


D Variable, with the number of characters 
in the record specified in decimal 


Variable, with the number of characters 
specified in binary. (See Note 1, Table E—9.) 


Undefined 


Block length Five ‘’n” characters specifying the maximum number of 
characters per block. (See Note 3, Table E—8.) 


Record length Five ‘’n” characters specifying: if ‘‘record format” is F, 
record length; if D or V, maximum record length 
including any count fields; if U, then undefined. (See 
Note 1, Table E—9.) 


Reserved Reserved for OS/3 use; currently ‘‘spaces’’. (See Note 2, 
Table E—8.) 


Buffer offset (optional) Two ‘’n” characters specifying the length in characters 
of any additional field inserted before a data block—for 
example, block length. This length is included in the 
block length. (See Notes 3 and 4, Table E—8.) 


Reserved _ 52-79 : Reserved for future standardization; must be “‘spaces’’. 
(See Note 2, Table E—8.) 





Cy 
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Appendix F. Consolidated Data Management 
Migration Considerations 


F.1. WHAT DO | HAVE TO DO TO MIGRATE TO CONSOLIDATED 
DATA MANAGEMENT? 


The answer is that the amount of effort varies with language of the program you want to 
migrate: that is, BAL, RPG Il, 1968 American National Standard COBOL, 1974 American 
National Standard COBOL, or FORTRAN. 

F.2. MIGRATION REQUIREMENTS 


The migration requirements for programs written in the various programming languages 
are discussed in the paragraphs that follow. 





F.2.1. BAL Programs | 


lf your program is written in BAL, you must redefine your files. This means that you must 
replace all basic data management DITF declarative macroinstructions. with the 
consolidated data management CDIB and RIB declarative macroinstructions. 


If you use disk files with your program, these must be converted (using data utilities) to 
MIRAM files before they can be used. 


You must replace all basic data management imperative macroinstructions with the 
appropriate consolidated data management imperative macroinstructions. These new 
imperative macroinstructions must be immediately followed by inline coding that checks 
the status of the operation being performed. This is necessary because consolidated data 
management always returns control inline. There is no provision made for contingency 
routine addresses such as EOFADDR and ERROR in the RIB macroinstruction. 


After you have modified your program, it must be reassembled and relinked before it can 
be executed. 


Note that if your program creates disk files, these files must be specified as MIRAM files 
oN in the job control stream used to execute the program. 
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F.2.1.1. OS/3 Sequential DTF Mode To CDI Macro Converter (DTFCD1I301) 


You can reduce the amount of effort required to migrate a basic data management BAL 
program that processes sequential files (card, tape, printer, or SAM disk) to consolidated 
data management by using DTFCDI301. This converter processes basic data management 
BAL source program modules that you have previously written to a library file. It produces 
a consolidated data management source program module and a listing that shows the 
actions taken by the converter. The consolidated data management source program 
module is automatically written to the original library file unless you specify otherwise. 
Those statements that cannot be converted or that require your attention are indicated by 
diagnostic messages on the listing. As you can see, the converter can save you 
considerable time because you only have to change your program where indicated. 


After you have modified your program, it must be reassembled and relinked before it can 
be executed. : 


The DTFCDI301 user guide, UA-0455 (current version) contains the detailed information 
you need to successfully use the converter. 

F.2.2. RPG Il Programs 

An RPG Il program does not require any modifications unless you want to want to use 
- workstations. It must, however, be recompiled and relinked before you can execute it even 


if you did not modify it. 


If your program uses disk files, these must be converted (using data utilities) to MIRAM 
files. . 


Note that if your program creates disk files, they must be specitied as MIRAM files in the 
job control stream used to execute the program. 
--F.2.3. 1968 American National Standard COBOL Programs 
Programs that are written in this language cannot be migrated to consolidated data 
_ management. They must first be converted to 1974 American National Standard COBOL. 
- F.2.4. 1974 American National Standard COBOL Programs — 
A program written in this language does not require any modification unless it uses disk 
files. It must, however, be recompiled and relinked before you execute it even if you did 


~ not modify it. 


If your program uses disk files, these must be converted (using data utilities) to MIRAM 
files before you can use them. | . 


Note that if your program creates disk files, they must be specified as MIRAM files in the 
job control stream used to execute the program. 
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F.2.5. FORTRAN Programs 


Your FORTRAN program does not have to be recompiled; however, you must update your 
unit definitions, reassemble them, and relink them with your program before you can 
execute it. . 


If you want to use workstations, you must modify your FORTRAN source program and 
recompile it. You must also update your unit definitions and include unit definitions for the 
workstations. These unit definitions must be reassembled and relinked with your program 
before you can execute it. 


If your program uses disk files, these must be converted (using data utilities) to MIRAM 
files. 


Note that if your program creates disk files, they must be specified as MIRAM files in the 
job control stream used to execute the program. 


» 
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‘oe Term Reference Page Term Reference Page 
C . CNTRL macro 7 | 
: device skip code table ~ Table. 7—4 7—22 
Card codes : DTFCD macro ae eee 3—3 
column binary 0.3.2 Cc—9 magnetic tape 9.4.10 9—62 
Fig C—2 C—9 nonindexed disk 15.7.15 15—103 
compressed C31. .  C—8 printer 7.4.3 7—21 
Fig. C—1 C—8 | punched card SAM 3.4.4 3—19 
data conversion C4. c—9 . using | » 3441 3—20 
Hollerith C.2.1 C—2 . . 
96-column punch _ Fig C—3 C€—11 | Code correspondences 
; column binary 0.3.2 C—9 
Card files See punched Fig C—2 C—9 
> card files. compressed card code 0.3.1 C—8 
Fig C—1 C—8 
Card punch . data conversion C.4 C—9 
card flow Fig. 3—1 3—20 description C.1 C—1 
characteristics Table A—2 A—3 EBCDIC/ASCII/Hollerith 0.2 Cc—1 
- codes, 96-column Fig C—3 C—11 a Table C—1 C—3 
_ using CNTRL macro 3.4.4.1 3—20 
Codes “ 
Card reader , 2 8. ASCH | See ASCII. 
characteristics Table A—1 A—2 device-independent control : ead 
See also punched card. character . - Table 7—1 7—6 
meg, 2 fees device skip + Table 7—4 7—22 
Character deletion “17534 17—45 EBCDIC “See EBCDIC. 
. shift See shift codes. 
Character mismatches 7.3 7-13 
. Combined files, diskette 3 ate 
Character mode, paper tape files BO description PAD OS A—_4 
character deletion, ae record processing 5.2.3 5—2 
input files - = ~ 17.5.3.1 17—45 YE 
description 17.2 — i Compressed card code 
17.3.3 17—10 description C31 C—8 
letter/figure shifting _ | * Fig-€—1 C—8 
_ and translation -  -oktiond 17—39 mode 0.4" C—9 
' ° 17.5.5 17—50 
specifying 17.5.2.2 1/—37 | Consolidated data management 
See also paper tape files. description 1948 1—1 
migration considerations Appendix F 
Characters, paper tape . Sig 
delete 17.3.) 17—5 Control characters . 
letter and figure shift 17.3.2 17—6 device-independent ~~ Table 7—1 7—6 
null 17.3.1 17—4 overflow and home paper Table 7—2 7—8 
stop L731. 1/—6 paper tape 17.3 17—4 
types 17.3 - 17—4 printer (DTFPR macro) a 3. 7—5 
Checkpoint dumps, bypassing 9.2.8.2 9—29 Current data pointer — : 156.11 15—34 
7 CLOSE macro Current 1/0 area 13.411 13—21 
diskette 9.4.4 5—12 '13B.5.9 13B—15 
ISAM SL? 11—25 | | Pra. 
magnetic tape “42 9—48 Current record pointer a 11.4.7 11—13 
of; nonindexed disk 15.7.2 15—63 . - ees 
, paper tape 17.4.2 17—18 | Current relative block address” 15,717 15—106 
. - 17.59 17—65 © et = 
printer 745 7—2] 


punched card 3.4.5 324 


Index 4 | 
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Term 


Reference Page “Term Reference Page 
Cylinder overflow with DTFPT macro keyword 
area, providing [412° 11—17 parameters Table 17—1 17—27 
control record 10.2 10—3 with DIFSD macro keyword aoNS ee 
: Fig. 10—1 10—4 | parameters Table 15—1 15—9 


Cylinders 
calculating space requirements 
formats, ISAM files 


DAM files 
description 
disk . 


Data 
conversion 
organization on typical 
~ peripheral devices 
*. partition, TRAM 
. Structure 
utilities 


Data blocks 
format, ISAM 


See also blocks. 


Data management error messages 
: description 
subcodes 


Data records, IRAM 
spanning disk sectors on 
~<a fixed sector disk 
with and without 


DD job contro! statement 

use 

with DTFCD macro keyword 
parameters 

with DTFDA macro keyword 
parameters 

with DTFIR macro keyword 

_ parameters 

with DTFIS macro keyword 

- parameters 

with DTFMI macro keyword 
parameters 

with DTFMT macro keyword 

"parameters 

with DTFNI and DPCA macro 
keyword parameters 

with DTFPR macro keyword 
parameters 


10.2.2.1 
Fig. 10—1 10—4 


eH oe 1.5.2 1—10 


15.3 15—4 
CA C9 
Fig 1-1 1-4 
1221 123 
13. ia. 
175. 1—18 
1022 10-8 


Fig. 10—4 10—9 


B.3.1 B—2 
Table B—1  B—3 
Table B—1A B—9 


Fig. 12-2 12-5 
Fig 12-1 12—4 


oe (5 


Jable3—1 3-13» 
Table 15—2. 15—12 
Table 13-1 13—16 
Table 11-3 1121 
Table 13B—1 13B—10 


‘Table9—1 9—4 


Table 15—3 15—17.. 


Table 7—3 7—14 


Deallocation, dynamic 
Deallocation statement (SCR) 


Declarative macroinstructions 
description 
IRAM 


magnetic tape 
MIRAM 
nonindexed disk file 
paper tape 

~ printer 
punched card 


Delete character 


Deleting records 


| Device allocation 


Device assignment set 
sample 
use of job control statements 


Device-independent control 
character codes 


Device skip code table 


Direct access files 
random retrieval 
See also DAM files. 


Direct access method 


Direct IRAM files 
adding records 
creating 
deleting records 
description 
extending 
processing 
reorganizing 
retrieving and updating 
records 


Direct retrieval 


Disk address, relative 


163° 16-8 
16.13 162 
16.1 112 


See DIFIR macro. 
See DIFIS macro. 
See DIFMT macro. 
See DIFMI macro. 
15.5," 15—7 
See DIFPT macro. 
See DIFPR macro. 
See DIFCD macro. 


1721 2- * 473 
17.3.1 Li=5 


_See record deletion. 


161 16-1 
16.12 16-2 
16.1.1 16—1 
Table 7—1 7—6 


Table 7—4 7—22 


15.7.14 15—97 
See DAM. 

13.1.2.3. 13—7 
13.1.2.1 13—5 
13:12:5 13—8 
lack. 13—1 
13.1.2.2 13—6 
13.1.2. 13—5 
13.1.2.6 13—8 
‘13.124 13-7 
See READ, KEY 
macro. 

See relative 


disk address. 
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Disk file labels Diskette 
description Dl D—1 characteristics Table A—4 A—9 
diskette D5 D—30 combined files 4230 44 

Fig. D—16 D—30 file label format D.5 D—30 
. | Table D—12 D—31 Fig. D—16 D—30 
file information group See file information Table D—12 D—31 
| group labels. files 1.3.3 1Pe7 
optional user standard See standard 42 4—] 
es labels, disk. FigcdSlo “Aan? 
volume information group j See volume informa- input files 42.1 4—3 
tion group labels. limitations 5.2.6 5—4 
output files 42.2 . 4—4 
Disk files . As record. formats 4,3 4—4 
access methods Section 15 Fig. 4—2. 4—5 
assigning space to file a 7 SAM _ . See SAM files, 
partition ~~ 15,.6.25 15—49 © . diskette. 
creating by sequential load 15.7.11.1  15—86 using 5.25 5-3 
description 13.6 1—8 —— 
dynamic deallocation . ; ~ | Double-buffering 17.5.1.4 17—30 
(SCRTCH) 16.3 16—8 ; . - 
extension error handling . B.3.3 B—12 | DPCA macro a kt a 
IRAM See TRAM.» description 164  15—5 
ISAM See ISAM. 15.5.4 15—16 
labels . . See disk file _ format . 1554 15-16 
labels. keyword parameter summaries Table 15—3 15—17 
nonindexed See nonindexed Table 15—7 15—58 
disk files. keyword parameters 15.6. . 15—20 
renaming (RENAME) 16.2 16—6 nonstandard forms of keyword 
updating and extending 15.7.9.2 15—78 parameters 156.37 15—57 
See also sequential disk files. 
2 i _ DIF error 17.5.9. 17—65 
Disk head movement ~~ 15.7.15 ~~ 15—103 
DTF fields 

Disk prep routine | ; L710 | deb , filenameC See. filename. 

. i et other B.4.2 B—15 

Disk sectors © 12.2.2 12—3 

DIF forms 1.6.1 1—12 

Disk space management a eae 
description 173 ~1—17 | DTFCD macro 
error codes B.3.2 B—10 . diskette 5.3 5—5 

Table B—2 B—11 | punched card SAM files 330 3-3 
OBTAIN macro 1641 —= 16—12 
VTOC | 16.4 ~  16—11 | DTFDA macro . . 
| description 15.2 15—3 

Disk space requirements, estimating a 15.3 15—4 

. indexed IRAM file 122.4 — 12—9 15.5.2 15—11 
indexed MIRAM file ~~ -13A.2.5 13A—9 format 15.5.2 — 15—11 
ISAM file a 10221, - 10-11 keyword parameter summaries Table 15—2 15—12 
ISAM index area 10.2.4 10—14 . Table 15—7 15—58 
nonindexed IRAM file 12.2.5 12—12 keyword parameters 15.6 15—20 
nonindexed MIRAM file 13A.2.6 13A—12 nonstandard forms of 

< . keyword parameters 15.6.37 15—57 

pow. Disk subsystem 

f ) . characteristics Table A—4 A—9 DTFIR macro > o> week . 
files See disk files. . description 138" 13—15 
flexibility 1.5.6 i—11 format 13.3 | 13—15 


keyword parameters — | 13.4 13—18 
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Term Reference Page Term Reference Page 
DTFIR macro (cont) 
nonstandard forms of . DIFSD macro 
keyword parameters 13.4.26 13—25 description 15.2 ‘Ga 
summary of keyword parameters Table 13—1 13—16 : 15.5.1 15—8 
format 15.9.1 15—8 


DTFIS file table 
filenameC 
other addressable fields 


DTFIS macro 
description 
format 
keyword parameter summary 
keyword parameters 
‘nonstandard forms of key- 
word parameters 


DIFMI macro 
description 
format 
keyword parameters 
nonstandard forms of 
keyword parameters 
summary of keyword parameters 


DIFMT macro 
description 
format 
keyword parameters 
nonstandard forms of 
keyword parameters 


DTFNI files, output 


DIFN| macro 
description 


format 
keyword parameter summaries 


keyword parameters 
nonstandard forms of key- 
word parameters 


DTFPR macro 
description 
parameter summary 


DTFPT macro 
basic parameters 
description 
file processing mode 
format 
summary of keyword parameters 


11.6.1 11—49 
11.6.2 11—49 
Table 11—4 11—49 


11.3 - 11—6 
11.3 ies 
Table 11—3 11—21 
11.4 11—8 
11.4.19 11—20 
13B.4 ~ 13B—8 
13B.4 13B—9 
13B.5 13B—13 
13B.5.24  13B—20 


Table 13B—1 13B—10 


9.2 9—1 
9.2.1 9—2 
Table 9—1 9—4 
929 ° 9—29 
Table 9—2 9—30 
15:7.9.5 15—80 
15.1 15—2 
15.4 15—5 
15.5.3 15—14 
15:5.3 15—14 


Table 15—3 15—17 
Table 15—7 15—58 


15.6 15—20 
15.6.37 15—5/ 
23 7—4 


Table 7—3 7—14 


17.5.1 17—28 
17.5 17—24 
17.5.2 17/—36 
170 17—25 


Table 17—1 1/—27 


keyword parameter summaries 


keyword parameters 
nonstandard forms of key- 
word parameters 


DTFSD output file, extending 
Dumps, checkpoint 


DVC job control statement 


Dynamic deallocation, disk 
file (SCRTCH) 


Dynamic extension, file partition 


Dynamic tape prepping and recording 
density 


EBCDIC code correspondences 


EBCDIC record and block formats, 
magnetic tape 


EBCDIC standard mode 


EBCDIC volume organization, 
magnetic tape 
file trailer label group 
first file header label 
(HDR1) 
multifile, end-of-file 
multifile, end-of-volume 
nonstandard 
second file header label 
(HDR2) 
single file 
standard 


unlabeled 


VOL1 label format 


Table 15—1 15—9 
Table 15—7 15—58 


15.6 
15.6.37 
15.7.9.3 
9.2.8.2 
9.3.1 — 
16.1.1 
16.3 


15.6.30 


9.3.3.2 


C.2 . 
Table C—1 


8.2.5 
Fig. 8—11 


C.4 


E.2.3 


E.2.2.1 
Fig. 8—2 
Fig. 8—3 
8.2.2 


E.2.2.2 
Fig. 8—1 
8.2.1 
E.2.4 

— B23 
Fig. 8—6 
Fig. E—1 
Table E—1 


15—20 
15—57 


15—79 


— 9—29 


9—31 
16—1 


16—8 


15—53 


as 


C— 


1 
w 


8—14 
8—14 


Cc—9 








UP-8068 Rev. 4 


SPERRY UNIVAC 0S/3 
BASIC DATA MANAGEMENT 


Index 7 © 





Term 


End-of-data (/*) job control statement 


End-of-data processing 
magnetic tape 
punched card 


End-of-file 
condition, tape 


input, address for routine 
recording logical, disk 


End-of-file handling routine, IRAM 


End-of-file handling routine, MIRAM 


End-of-file label 
end-of-volume coincidence 


first 


second 


End-of-record stop character 


End-of-tape routine, paper tape 
input files 


End-of-volume condition 

End-of-volume label 
end-of-file coincidence 
first 


second 


End-of-volume procedures, forcing 
ENDFL macro 


EOF1 and EOV1 labels 
ASCII 


contents 
description 

EOF2 and EQV2 labels 
ASCII 


contents 
description 


Reference Page 


2.32 2—3 
g225 9—12 
3.3 3—5 
8.2.1 8—2 
Fig. 8-2 8—3 


15.6.4 15—~25 
19.7.11.3  15—89 


13.4.4 13—19 


13B.5.3 13B—13] 


8.2.4.1 8—9 


Fig. 8-10 8—13 


See EOF1 and 
EOV1 labels. 
See EQF2 and 
EOV2 labels. 


1756 17-60 


17.5.4 17—49 


8.2.1 
Fig. 8—3 


7 1. 
Gr Bo 


8.2.4.1 8—9 
Fig 8—10 8—13 
See EOF1 and 
EOV1 labels. 

See EOF2 and 
EOV2 labels. 


See FEOV macro. 


115.23 11-30 


Fig. E—10 E—23 
Table E—10 E—24 
Table E—4 E—11 
E23 E—9 
Fig E—4 E—10 


Fig. E—11 E—25 
Table E—11 E—26 
Table E—5 E—13 


UES E—9 


Fig, E—5 E—12 


Term 


Error and exception handling 
card reader 
data management 
description 
disk file extension 
disk space management 
flagging procedures 


ISAM 

messages, system 
nonindexed disk 
printer 


return of control 


system error messages 


Error codes, disk space management 


Error handling routines 
card reader 


magnetic tape 
MIRAM . 
nonindexed disk 
printer 


Error messages 
system 


tape label processing 


Error processing 
paper tape files 


See also error handling routines. 


Errors, parity 

ESETL macro 

Expiration date 
field, ASCII tape labels 
SCRTCH macro 


EXT job control statement 


Extending existing disk files. 


Extension, tape files 


Extension error handling, disk file 


Reference Page 


3.5 3—25 
B.3.1 B—2 
Bl | B—1 
B.3.3 B—12 
B.3.2 B—10 
See flagging 
procedures. 

11.6 11—49 
B.2.1 — B—2 
See system error 
messages. 

15.8 15—111 
7.6 7—28 
1.55 1—11 
B.2 B—1 
B.3 B—2 
B.3.2 B—10 
Table B—2 B—1] 
3.3 3—6 


13.4.5 13—19 
11.43 11—10 

9.2.2.4. 9—12 
13B.5.4 13B—13 
15.6.6 15—26 
7.3 7—8 


See system error 
messages. 
9.3.7 9—43 


17.5.9 17—65 


See parity errors. 


11.9.5.4 11—48 


E.3.2.3 E—16 
16.3 16—8 
16.1.1 16—1 
15.7.9.2 15—78 
19.13:3 15—79 
83.6 9—4]1 
B.3.3 B—12 
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Term Reference Page Term Reference Page a 
F File organization 
IRAM 12.2 12—3 
FEOV macro ISAM 10.2 10—3 
magnetic tape 9.4.8 9—59 magnetic tape 82 8—] 
nonindexed disk 157.7 15—73 MIRAM 13A.2 13A—3 
nonindexed disk 14.2 14—2 
Figure scan table 17.5.5 17—50 
_ File partitions 
Figure shift character 17.3.2 1/—6 assigning initial disk space 156.25  15—49 
dynamic extension 15.6.30 15—53 
Figure shifting and translation indexed ISAM 10.2 10—3 
input files, character mode 17.5.3 17—39 Fig 10-1 10—4 
output files, character mode 17.5.5 17—50 initializing position 15.7.6 15—7? 
IRAM 12.2 12—3 
File accessing options 114.1 11—8 12.23 125 
Fig, 12—5 12—7 
File control block (FCB), SCRTCH nonindexed disk 14.2.1 14—3 
macro 16.3 16—8 positioning to relative 
block address 15.7.18 15—108 
File creation date 9.3.4.4 9—39 selected, accessing 15.7.4 15—68 
specifying address for 
File description labels, diskette 42 4—3 - _DTFNI files 15.6.17 15—39 
D.5 D—30 subfile processing 15.6.27 15—50 
15:75 15—70 
File expiration date 9.3.4.3 9—38 ie 
. | File processing Ae 
File header labels, tape mode, changing for an 1/0 . 
first (HDR1) E.2.2.1 E—4 tape file 945 9—54 
second (HDR2) E.2.2.2 Epc mode, setting (SETF macro) 15.7.8 15—74 
See also HDR1 and HDR2 labels. optional See optional file 
Pa processing. 
File identifier 9.3.4.1 9—36 specifying with one volume 
a online at a time 13.4.24 13—24 
File information group labels, disk 13B.5.22 13B—19 
chain Fig D—7 D—12 TYPEFLE keyword 3.3 3—10 
description D.3 D—12 9.2.2.3 9—1] 
format 1 D.3.1 D—13 utility 1.7.5 1—18 
Fig D—8 D—13 
Table D—6 D—14 | File protection ya 1—17 
format 2 D.3.2 D—18 
Table D—7 D—21 | File recovery support 
format 3 0.3.3 D—25 IRAM files 13.5.1 13—26 
Fig D—13 D—26 MIRAM files 13B.6.1 13B—21 
Table D—11 D—27 
File sequence number 9.3.4.5 9—39 
File label information (LBL) statement 9.3.4 9—36 
File serial numbers, checking 9.3.4.2 9—36 
File lock, suppressing 
IRAM 134.15 13—22 | File sharabilit 1141 11-8 
ISAM ai. aiig |)” " 1614163 
nonindexed disk 15.6.16 15—38 Tale 16—1 16—4a 
MIRAM 13B.5.12 13B—16 
File lock feature 16.1.4 16—3 ( | 


Table 16—1 16—4a 


BOP 
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Term 


File trailer label group 
description 


EOQF1 and EQV1 field 


descriptions 


EOF1 and EOV1 formats 
EOF2 and EOV2 field 


descriptions 


EOF2 and EOV2 formats 


File type specification (TYPEFLE) 


IRAM 

ISAM 
magnetic tape 
paper tape 
punched card 


Filename-addressable fields, DTFIS 


file table 


FilenameC 
card reader 
description 
ISAM 


magnetic tape files 


nonindexed 
paper tape files 


printer 


significance of bits 


Files 
ASAM 
assigning 
DAM 
disk 
diskette 
IRAM 
ISAM 
magnetic tape 


MIRAM 
multivolume 
nonindexed disk 
optional 

paper tape 


printer 
punched card 


SAM 


SPERRY UNIVAC 0S/3 
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Reference Page 


a | 


Table E—4 E—11 
Fig E—4 E—10 


Table E—5 E—13 
Fig. E—5 4 =E—12 


13491 1393 
11415 11-18 


22.2.3 9—1] 
Lf O41 1/—28 


d.3 3—10 
Table 11—4 11—49 


3.5.1 3—25 


B.4.1 B—13 
1161 11—49 
9.2 9—2 


15.8.1 15-—111 


Tio8 17—65 


Table 17—2 17—66 


7.5.1 7—28 
Table B—3 B—13 
10.3 10—18 
16.1 16—1 
See DAM files. 

See disk files. 

See diskette files. 
See IRAM files. 

See ISAM files. 


See magnetic tape 
files. 

See MIRAM 

files. 

See multivolume 
files. 

See nonindexed 
disk files. 

See optional 

file processing. 
See paper tape 
files. 

See printer files. 
See punched card 
files. 

See SAM files. 


Term 


Fixed-length records 
diskette 
ISAM 


keyed, nonindexed disk files 
nonindexed disk files 


See also record formats. 


Fixed, unblocked records 
(paper tape) 
followed by interrecord gaps 


format 
shifted, work areas 


Flagging procedures, error 
description 
filenameC 
other DTF fields 


Format labels, retrieving specific items 


Format 0 label, disk 
contents 
description 


Format 1 label, disk 
contents 
description 


Format 2 label, disk 
contents 
description 
IRAM/MIRAM information area 


ISAM file information area 
library file information area 
nonindexed files 

Format 3 label, disk 


contents 
description 


Format 4 label, disk 
contents 
description 


Index 9 
Update C 


Reference Page 


4.3.1 4—4 

10.2.1 10—5 
Fig. 10—2 10—6 
Fig. 14—4 14—12 
14.3.1 14—/ 
Fig. 14—2 14—8 


Fig. 17—5 17—10 
Fig. 17-6 17—11 
Fig. 17—7 = 17—13 
Lia.3 17—10 
Fig. 17-—9 17—15 


B.4 B—12 
B.4.1 B—13 
B.4.2 B—15 


16.4.1.1 16—14 


Table D—5 D—11 
D.2.5 D—11 
Fig D—6 D—l11 
Table D—6 D—14 
D.3.1 D—13 
~ Fig D—8 D—13 
Table D—7 D—21 
D.3.2 D—18 
Fig. D—11 D—20 
Table D—9 D—24 
Fig D—10 D—20 
Table D—8 D—23 
Fig. D—12 D—21 
Table D—10 D—25 
Fig D—9 D—19 


Table D—11 D—27 


033 D—25 
Fig. D—13 D—26 
Table D—2 D—6 
D.2.2 D—4 


Fig D—3 D—5 
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Term 


Format 5 label, disk 
contents 
description 


Format 6 label, disk 
contents 
description 


Forms, printer 


Forms overflow 
code, DIFPR macro 
print action (PRTOV macro) 
VFB statement 


Forms advance 


Gangpunch—reproduce 


Gaps, interrecord 
General registers 


Generation number, file 


GET macro 
diskette 
ISAM 
magnetic tape 
nonindexed disk 
overlap mode 
paper tape 
punched card 
use of IOREG keyword, processing 
input disk files sequentially 


Hardware constraints 


HDR1 label 
ASCII volume 
contents 
description 


field description, ASCII volume 


SPERRY UNIVAC OS/3 
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Reference Page 


Table D—3 D—9 
D.2.3 D—8 
Fig D—4 D—8 
Table D—4 D—10 
D.2.4 D—9 
Fig D—5 D—10 


See printer forms. 


7.3 7—11 
74.4 7—24 
6.4.4.2 6—9 
7.3 7—10 
1.7.5 1—18 
See interrecord 
gaps. 

See save area 
specification. 

9.3.4.6 9—39 
5.4.2 5—8 
115 5:2 11—44 
9.4.4 9—52 
15.7.12 15—94 
3.3 3—8 
17.4.3 17—20 
3.4.2 3—15 


Table 15—9 15—95 


1.5.6 i—11 
Fig E—8 E—19 
Table E—2 E—6 
E.2.2.1 E—4 
Fig, E—2 E—5 
Table E—8 E—20 


Term 


HDR2 label 
ASCII volume 
contents 
description 


field description, ASCII 
volume 


Header labels 
file 


user 
volume 
Hole-count errors, DIFCD macro 
Hollerith code 
ASCII/EBCDIC/Hollerith 
correspondences 
description 


Home paper control character codes 


Home paper position, VFB statement 


Image mode 


Imperative macroinstructions 
description 
diskette 
indexed ISAM 


invalid 

ISAM files 

ISAM files without index 
structure 


magnetic tape 
nonindexed disk 


paper tape 
printer 
punched card 


Index 10 
Update C 


Reference Page 9 


Fig E—9 E—21 
Table E—3  E—9 
E.2.2.2 E—/ 
Fig E—3 E—8 


Table E—9 E—22 
See file header 
labels. 

See user header 
labels. 


See VOL1 label. 


3.3 3—5 


C.2 C—1 
Table C—1 C—3 
C.2.1 C—2 
Table 7—2 7—8 


6441 6-9 J 


c.4 c—9 

1.6.2 1—14 

54 5—6 

11.2.1 112 

Table 11—1 11—3 

17.59  17—65 

11.5 11—23 
11.2.2 113 

Table 11—2 11—4 

94 9—43 

15.7 15—59 
Table 15—8 15—61¢ 
17.4 17—15 >" 
74. 7-15 

3.4 313 
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Term 


INDAREA 
buffer 
_ table: in main storage 


Index area length, IRAM 


(INDS keyword) 


Index area length, MIRAM 
~ (INDS keyword) 


Index blocks, IRAM 
coarse- and mid-level 
fine-level, three sectors 
naming. main storage location 


~ Index blocks, ISAM 


calculating space 
describing in main ee 
cee 


format — fe 
loading top index into 
main storage 


ts Index partition, RAM 


Index registers © 


Index structure 


IRAM 

ISAM, eliminating 
(INDEXED keyword) 

MIRAM 


indexed IRAM files 


adding records during cuinial 
index active 

Creating 

deleting records 

extending 

processing 

reorganizing 


retrieval and update, index 


inactive 
retrieving and updating, 
index active 


Indexed ISAM files 


Indexed MIRAM files 
adding records during retrieval 
creating 
deleting records 
extending 


Reference 
10.2.5 


Fig. 10—8 


13.4.7. 


See. register 


- specification. 


12.2.3 


11.4.5 © 
13A.2.3 


13:2:4 


13.21 
13.2.6 
13.2.2 


13.2 
13.2.7 ; 


13.2.5 
13.2.3 
11.2.1 
13B.3.4 
13B.3.1 


13B.3.5 
13B.3.2 


Page 


10—16 


10—17 


13—20 


13B—14 


12—6 
12—5 
13—20 


10—14 
ll—11 
10—3 

10—12 
10—12 


10-16 


23 


12—6 
12—7 


12—6 


11—12 
13A—7 


13—12 
13—10 
13—14 
13—11 
13—9 

13—14 


13-13 


13—11 


11—2 


13B—8 
13B—6 
13B—8 
13B—6 


Term =: 


processing 
reorganizing 


retrieving and updating records 


. Indexed. random access method 


Indexed sequential access method 


Input blocks, updating 


Input files 
diskette 
label processing, ASCII tape 
paper tape 
punched card SAM 
tape, specifying aireenon 
TYPE keyword 


Input/output, multisector 


Input/output buffers (areas) 


card reader 
IRAM 


ISAM 

loading top index in main 
storage Lee 

magnetic ‘tape 


nonindexed disk 
Paper tape 
printer - 

Input record processing | 


diskette SAM files 
IRAM files 


_Interlace, record 


Interrecord gaps, paper tape files 


description 

input, binary mode 
input, standard mode 
output, either mode 


IRAM files — 
adding records, input 
buffer size 
defining (DTFIR macro) 
direct - 


end-of-file handling routine 
error routines 


Reference . Page 


13B.3.  — 13B—5 
13B:3.6 . 13B—8 
13B.3.3. 13B—7 


See IRAM. 


See ISAM. 

See sdatiee 

input blocks. 
AOL. 3 

£3.12: F—15 

See paper tape files. 

32.1 .. 3-1 

9.2.5.1. 9—22 
13.421 13—23 
he 523 
ee 


13.49 -. 13—20 
13.4.10 13—21 
13.4.11 13—21 
1146- l1~—12 


1025 10-16 


9.2.2.1 9—10 
923.1 . 9—13 
15.6.9 15—33 


15.610  15—34 
17.5.1.4 17—30 


Fig.-17-—-4 17-9 
WBeue: JR 
a | 


13.4.25 13—24 


15.68 15—30 


17.3.4 17—10 


Fig. 17-7 = 17—13 


Fig. 17-6 17—12 


+ Figd7—5 17—11 


1342 «13419 
J 139 22 41919 


13.3 ©, 13—15 
See direct IRAM 
files. 

13.4.4 13—19 
13.4.5 13—19 
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: Term cae 


es 


files (cont) 
file’ accessing options 


file type 
index area length 
indexed . 


input or output record 
processing, work area 


| 1/0 area identification 


key lengths 
_ key retrieval 


locating relative disk 
address 


- Naming location for rites blocks. 


number of bytes preceding keys‘: 


optional files 
pointing to current 1/0 area 
processing, nonindexed 
processing, one volume online 
ata time 

processing by key 

record length 

retrieval and lead modules 
sequential 


suppressing file lock 

updating records 

verifying ascending record key. 
order during file creation 

verifying output records 


TRAM ‘oiits and file conventions 


coarse- or mid-level index sector 


‘concepts 


data partition 
data records spanning disk sectors 
on fixed sector disk 


data records with and without keys. 


description 
entries in index partition 
estimating disk space 


file organization 


fine-level index block of 


. three sectors 


‘index structure 


search of 4-level index 


au error handling 


“ISAM file information area, disk 
| ~ format 2 label 
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Table D—8 


D—23 .. 


Reference Page, | ‘Term 
pote” A ISAM files 
1341 13-18] addressable fields in DTFIS file 
-13.4.21 13—23. table. 
13.4.7 13—20 
» See indexed -IRAM: ASAM files 
files. ASAM record formats 
#3 a current record pointer 
13.4.25 13—24 cylinder overflow 
13.49.°° 13—20]... data blocks 
13.4.10 13—21 
13.4.13 13—21 defining (DTFIS macro) 
13.412 » 13—21 deleting records 
en a description 
13.419 - 13—23 ea: 
13.46.  13—20 error exit 
13.4.14 13—22 file accessing options 
13.417. 13—22 filenameC 
134.11. 13—21. functions and operation. 
13.1 13—1 imperative macro instructions 
oO EPLS tle index area in main storage 
13.4.24 13—24 ‘index area space requirements 
13.4.8 13—20 index blocks 
(13.418 13—23. index structure 
13.4.16 13—22 
See sequential indexed,. processing 
IRAM files. initializing (OPEN macro) 
13.415. © 13—22. inserting. new records 
13.4.22 13—24 1/0 buffers 
: ‘loading and extending 
-13.4.20 13—23 loading top index. 
13.4.23 13—24 
BES multivolume 
organization 
‘Fig. 12—4 12—6 parity check 
12.1.1 12—1 © random processing 
12.2.1 12—3 record: formats 
record keys 
Fig, 12—2 °° 12—5 record size and format 
Fig? 12—1 12—4 record work areas 
24°" “FO )'s retrieval search argument 
12.2.2 12—3 sample load program 
12:24 ~ ~12—9 save area 
12.2.5 aa -. > sequential processing 
12.2 12—3 |... | space requirements 
structure’ 
Fig. 12—3 12—5 suppressing file lock  .- 
12.23 °- 12—6-}- terminating (CLOSE macro) 
~ Fig. 12—6 12—8 type of retrieval 
B.2.1 —B—2 
D32 .. D—18 
Fig. D—10 D—20. 


Index.12: © 2. 2.7: 
Reference Page 
11.6.2: © 11—49 
Table 11—4 11—49 

- 103 © 10—18 
10.3.1 10—22 
11.4.7 11—13 
11.412 © W—17 
10.22: © «10-8 
11.4.2 11—9 
113°) --11—6 
11.2.3 11—4 
LS. 4 i—10 
10.1.- . 10—1 
11.43 11—10 
W4d, +118 

- 11.6.2. 11—49 
SAD 2% 11—1 
115 - 11—23 
11.4.4 11—11 
10.2.4 10—14 
10.2.3 10—12 
11.2.2 11—3 
11.4.5 11—12 
11.2.1 11—2 
11.5.1.1 11—24 
11.5.3 11—31 
11.4.6 11—12 
11.5.2 ~ 11—26 
10.2.5 10—16 
Fig. 10—8 10—17 
10.4 10—22 
10.2... 10—3 
11.4.17 11—19 
11.5.4 11—35 
10.2.1 10—5 
11.4.10 11—15 
11.4.13 11—17 
11.4,18 11—19 
11.4.9 11—14 
11.7.1 11—50 
11.4.14 11—18 
11:5.5 11—40 
10.2.2.1 10—11 
Fig. 10—7 10—13 
11.4.11. 11—16 
11:5,1.2 11—25 
11—18 


ee, 
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Term 


Job control functions 


Job contro] statements 
assigning tape device (DVC) 
defining your logical file (LFD) 
end-of-data (/*) 
magnetic tape files 
sample programs 
«SCR «: 
~ specifying tape file label 
information (LBL) 
specifying tape volume. 
information (VOL) 
start-of-data (/$) 
use . 


Key fields, nonindexed files 


‘Key search 

assigning to multiple tracks 
ISAM. 
nonindexed disk 


Keys 
direct retrieval and updating 
of input blocks 
IRAM data records 
IRAM processing 
ISAM files 
length of block, nonindexed 
disk. files 
lengths, |RAM 
number of bytes preceding, IRAM 


output of sequential DIFNI files. 


record, length and location 

record, verifying ascending order 
during file creation 

retrieval, IRAM 


Reference 


9.3.1 
9.3.2 
2.3:2 


9.3 


3.7 
16.1.3 


9.3.3: 


23h: 3" 
16.1.1: 


14.3.3 
Fig. 14—4 


15.6.26 . 
11.4.9 
15.6.12 


15.7.14.2 
13.4.8 
10.1 


15.6.13 — 
13.4.13. 
13.4.14 
15.7.9.5 
11.4.10 


13.4.20 


| aA l2 


-Page Term 
L : 
1—16 Label processing routine 
9—31 | Label standard level field, ASCII 
9—32 tape labels 
2—3 
9—31 Labels 
3—25 |: disk files 
16—2 EBCDIC 
9—36 format. 
LBL statement 
9—33 
2—3 magnetic tape 
16—1 
processing 
standard 
user 
Lace factor 
LBL job control statement 
‘checking volume and file 
serial numbers 
description 
effects on OPEN transient 
- file creation date 
file expiration date 
file generation and version numbers 
file identifier / 
1410 file sequence number 
14—12 LBRET macro 
magnetic tape 
1550 nonindexed disk 
ine LCB job control statement 
LCB statement specification 
description 
0768 printer 
15—101 0770 and 0776 printers 
en 0773 and 0778 printers 
10-1 Leader, paper tape 
15—36 
321 Letter scan table 
13—22 
1520 Letter shift character 
11—15 Letter shifting and translation 
13-23 ‘Input files, character mode 


13—21 | ual files, character mode 


Reference Page 


15.6.14 15—37 
D4. ‘ D—28 
E.3.2.2 


E—16 


See disk file labels. 
See EBCDIC volume 
organization. 

See format labels. 
See LBL job.con- 
trol. statement 


See magnetic tape 


labels. | 

See LBRET macro. 
See standard labels. 
See user labels. 


1568. 15—30 
9342 9-36 
934: 936 
16.1.1 i6—1 
Table 9—3 9—37 
9344 9—39 
9343 9-38 
9346 9-39 
9341 9-36 
9345 939 
9.4.9 9—60 
15.7.3 15—64 
16.1.1 16—1 
6.4.2 6x9 
6423. 68 
6.422 68 
6.421 6-8 
17.2.2 17-3 
17.5.5 17—50 

1732- 1746 
17.5.3 17—39 
1755 17—50 
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Term . 
LFD job control statement 


Library file information area, 
disk format 2 label 


Lines 
skipping and spacing 
truncation 


Linkage editor, description 
Load code buffer 

definition 

' interchangeability 

LCB statement specification 
Load. program, sample ISAM 
‘Load sequence 

initiating (SETFL macro) 

terminating (ENDFL macro) 
Logical end-of-file, recording 
Logical file definition (LED) 
: Logical’ records 
ISAM data blocks 
ISAM files 


punching, paper tape 
reading 


Macroinstructions 
assembler rules for operand 
field 
declarative 


imperative 


Reference Page 


Disc 9—32 
16.1.1 16—1 
D.3.2 D—18 


Fig. D—12  D—21 


6.1 6-1 


7.5.2 7-28 
1.7.4 I-17 
6.1 61 
6.4.1 6—7 
6.4.2 6-7 


171 11—50 


11.521 11-27 
11.523 1130 
15:7.113  15—89 
932. 9-32 


Fig. 10—4 10—9 


10.4.4 10—1 
10.2.1 10—5 


1744 17/—22 


See GET macro. - 


1.6.3 i—14 
See declarative 
macroinstructions. 
See imperative 
macroinstructions. 


Term 


Magnetic tape files 


description 
extending 
imperative macros 
labels 


multivolume 
organization 


record and block formats 


volume and file organization 


See also SAM files, magnetic. tape. 


Magnetic tape labels 


ASCII 


effects of VOL and LBL 
statements on OPEN transient 


error messages 


header, eliminating tape mark 


LBL statement 


OS/3 system standard 


padding 


processing (LBRET macro) 


special handling 
specifying type 


Magnetic tape prep routine _ 


Magnetic tape volume and file 


organization 


ASCII standard record and 


block formats 
description 


EBCDIC nonstandard 


EBCDIC standard 
EBCDIC unlabeled 


Messages, error 


See error messages. 


| MIRAM files 


buffer size 


defining (DTFMI macro) 
end-of-file handling routine 


error routine 


file accessing options 


index area length © 


\/0 area identification (data buffer) © 


key lengths 


locating relative disk address 


naming index area 


LO 


See magnetic 
‘tape volume and 


Page 


1—7 
9—4] 
9—43 


9—40 
1—8 

8—14 
8—14 


Reference. 
1.3.5 

9.3.6 

9.4 

See magnetic: 
tape labels. 
9.3.5 

Fig. 1—2 
8.2.5 

Fig. 8—11 


file organization. 


See ASCII 


standard magnetic 
tape labels. 
Table 9—3 9—38 
U3) 9—43 
9.2.6.2 9—24 
9.3.4 9—36 
See system 
standard tape labels. 
E.4 E—16 
9.4.9 9—60 
9.2.6.3 9—24 
9.2.6.1 9—23 
1.7.1 1—15 
8.2.5 8—14 
8.2. 8—1 
8.2.2 8—2 
8.2.1 8—2 
8.2.3 8—8 
13B.5.2 . 13B—13 
13B.4 13B—8 
13B.5.3  13B—13 
— 13B.5.4 13B—13 
‘13B.5.1. 13B—13 
_ '13B.5.6 13B—14 
13B.5.7° 13B—14 
~13B.5.8 13B—15 
13B.5.11 13B—16 
~ 13B.5.20 13B—19 
138.55 13B—14 
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_ MIRAM files (cont) 


number of bytes preceding keys 

optional’ files 

pointing to‘ current 1/0 area 
(data buffer) 

Processing mode 

processing one volume online | 
at a time . 

processing type of operations 

record control byte 

record format 

record length 

record processing, work area 

suppressing file lock 

verifying output records 


~ MIRAM formats and file conventions 


coarse- or ‘mid-level index block 
concepts _ 
data partition 
data record formats 
data record slots spanning 
physical block or sector boundaries 
entries in index partition 
estimating disk space 


file organization 
Modes 

data conversion, cards 

Paper tape 


punched cards 


Multifile sets, ASCII labels 
multivolume 


single-volume 


Multifile volumes, reel organization 


EBCDIC nonstandard 

EBCDIC standard labeled tape, 
end-of-file condition 

EBCDIC standard labeled tape, 
end- al: volume condition 


Multisector V0, diskette 


Multivolume files 
indexed TRAM 


ISAM 
nonindexed disk 
tape SAM 


SPERRY UNIVAC OS73 - 
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Reference 


13B.5.11 © 


~~ 13B.5.14 


138,59 
+ 138.5.13 


"13B.5.22° 
“13B5.15 


13B.5.16 
13B.5.16 
13B.5.18 
13B.5.23 
13B.5.12 
13B.5.2.1- 


Fig. 13A—4 
13A.1.1 
13A.2.1 © 
Fig. 13A—1 


Fig. 13A—2 
13A.2.2 
13A.2.5 
13A.2.6 
13A.2 


C.4 
17.2 
17.5.2 
3.3 


Fig. 8—9 
Fig. 8—10 
Fig. 8—8 © 
Fig. 8—5 


Fig. 8—2 


‘Fig. 83 


9.2.4 


Page 


13B—16 |- 
13B—17 |. 


13B—15 | 


13B—16 


13B—19 
13B—17 
13B—17 
13B—17 
13B—18 


-13B—20 


13B—16 


-13B—19 


13A—7 
13A—2 


13A—3 
13A—4 


13A—5 
13A—6 
13A—9 
13A—12 
13A—3 


c—9. 
i: 


17—36 


3—/ 


8—12 
8—13' 
8—11 


87. 
g—4 
g—5 
5—3 
13—9 
B= 
10—22 
14—2 


9—30 
9—40 


Term 


Multivolume sets, ASCII label 
configuration 
end-of-file and end-of-volume 
coincidence 
multifile 
single-file, single-volume 


Nonindexed disk files 

access methods 

accessing options 

address for routine on end- “ input 
file or .partition 

assigning: initial disk space to 
file partition ‘ 

block keys, length 

block size 

closing (CLOSE macro) 

current relative block address, 
accessing (NOTE macro) 

declarative macros 

defining (DTFNI macro)... 

defining type 

description 

direct access, defining (TFA 
macro) ss 

disk head movement to track 
controlling (CNTRL macro) 

dynamic extension of file 
partition 

end-of-volume procedures, forcing 
(FEOV macro) 

error and. exception handling 

error processing 

file lock, suppressing 

fixed-length records 


format 2 labels 


imperative macros 


index register, current-data pointer 


initializing position of:file or. 
partition 

1/0 buffers 

IRAM 


Index 15 
Reference Page 
Fig, 8-10 8—13 
Fig 8-9 8—12 
Fig. 8—7 8—10 
151 15—1 
15.6.1 15—21 
1564 18-25 
15.625 1549 
15.613.  15—36 
1563°.- 15-22 
‘1872 16-63 
167.17. 15—106 
155: 15—7 
15.5.3 15—14 
156.29. 15—5] 
iat 14—1 
1552. 15-11 
157.15. 15103 
15.630 15—53 
15.7.7 15—73 
15.8 15—111 
16.66 15—26 
15.615.  15—38 
143.1. 14—7 
Fig 14—2 14—8 
032 D—18 
Fig D—9 D—19 
157. s«15—59 
Table 15—8 15—61 
15.611 .. 15—34 
157.6: 1572 
156.9... 15-33 
12.25 12—12 
Aion . sce 
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Nonindexed disk files (cont) 


key search | ae 
keyword parameter summary 
label processing routine address 


labels 


opening (OPEN macro) 
optional files 
optional key fields 


optional standard user labels 

optional user labels, processing 
(LBRET macro) 

0S/3 DAM 

0S/3 nonindexed file access method 

08/3 SAM 

output (PUT macro) 

output, short variable blocks 
(TRUNC macro) i: 

parity check of output 

‘parity errors 

partition control appendage 
(DPCA ‘macro) 

partitioning 

partitions ‘for DTFNI files 

positioning file or partition to - 
relative block address 
(POINT macro) 

processing mode, setting (SETF. : 
macro) - 

random output of records 
(WRITE macro) 

random. retrieval from direct 
access files (READ macro) 

READ,: |D- macro 

READ, KEY macro 

record formats 


record interlace factor 

record. size 

records, retrieving (GET macro) 
records, skipping (RELSE macro) 
register for residual space 
relative addressing 

relative disk address 


save area for general registers’ 

selected file partition, accessing 
(SETP macro) 

sequential, defining (DTFSD macro) 

sequential processing in.a work area 

subfiles in. partitions 


15.6.12 
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Reference - Page 


Table 15—7 15—58 | 
15.6.26 15—50 
15.6.13 15—36 
See disk 

file labels. 

15.7.1 15—62 - 
15.6.16 15—38 


14.3.3. 14—10 
Fig. 14—4 14—12 


14.2.4 14—5 
15.7.3 15—64 
153 15—4 
15.4 15—5 
152... . [5d 

15.79 15—75 
157.10 1582 
15833  15—55 


156.5 15—26 


1554. 15-16 | 


15.78 15—74 


15.7.11 °°  15—84 
—15.7.14- 15—97 
-15.6.18 15—40 
~ 15.6.19 15—40 
14.3 14—6: 
15.6.20 15—40 
Fig. 15—1 15—24 


Table 15—6 15—41 


156.8 — 15—30 
“% 15.621 - 


15—42 

15.712  15+94 
15.713 15-96 
15.632  15—54 
156.22  15—42 
15.6.7 © 15-28 
15.6.24 1546 
15.6.23 15-45 
15.7.4 15—68 
15.5.1 15—8 
15.6.34 15-56 
14.2.2 14—3 
15.6.27 1550 


15.7.5 15—70 


1535; 


Term .- 


Nonstandard volume organization, 


system standard labels 


update processing mode 
user: trailer label processing 


variable-length records 


waiting for 1/0 completion 


(WAITF macro) 


WRITE, AFTER and WRITE, -RZERO 


macro. issue 
WRITE, ID macro 
WRITE, KEY macro 


Nonindexed file. processor system 


EBCDIC 


NOTE macro. 


Null character 


142 dete 1h3 
156.17 15-39 
15.7.18 15—108 


OBTAIN macro 


description 


retrieving specific format 


label items 


OPEN macro 


Operand field, assembler rules 


diskette 


effects of VOL and LBL Seirus 


on OPEN transient 
ISAM 
magnetic tape 
nonindexed disk 
paper tape 


printer | 
punched card 


Operator communications 


Index 16 


Reference 


14.2.3 
15.6.31 


15.6.28 


14.3.3 
Fig. 14—3 


157.16 
15.6.2 


15.6.35 
15.6.36. 


15.1 


See EBCDIC 
nonstandard 


organization. 
15.7.17 
173 


16.4.1 


16411° 


5Al 
Table 9—3 


- 115.11 


9.4.1 


15.7.1 _ yet 


17.4.1. 
1759 
741 
34.1. 
1.6.3 


L:i3 


volume 


15—106 


17—4 


16—12 


16—14 


UP-8068 Rev..4 .. 


Term 


Optional file processing 
~  |RAM © 
magnetic tape 
MIRAM 
nonindexed disk 
paper tape 
printer 
punched card 
sequential. output, nonindexed disk 


Optional user labels, disk 
nonindexed disk 
processing 
standard’ 
standard header 


standard trailer 


Optional user labels, tape 


08/3 DAM 


OS/3 processing, ASCII tape labels 
0S/3 SAM 


0/4 paper re system, compatibility - 
“with OS/3. 


: outeut files 

blocked records, sequential disk 
diskette _ 

extending ‘existing DTFSD 

label processing, ASCII tape 
paper tape 


punched card SAM 
sequential DTFNI with keys 


Output records 
diskette SAM files 
parity check, ISAM files 
processing in a work area, IRAM 
random, to disk 
undefined, standard mode paper tape 
file 
verifying, IRAM 
verifying, MIRAM 
See also PUT macro. 


Overflow 
adding new record in existing 
file 


SPERRY UNIVAC OS/3 -. 
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Reference 


13.4.17 © 
9.2.8.1 
13B.5.14 
15.6.16 
17.5.7 

7.3 
3:3 | 
15.7.9:6~ 


14.2.4 
15.7.3 
D.4.1 


Fig. b—14 
D.4.2° * 


Fig. D5 


E24 


15.3 


E311 


~* See paper 


tape files: 
322 
15.7.9.5 


5.2.2 

11.4.17 
13.4.25 
15.7.11 


Fig. 17—3 
13.4.23 
13B.5.21 


11.5.3.1 
11.5.3.2 


Term 


_ Page ) 
ne 2 area, ISAM files 
13—22 ‘control character codes 
9—28 |. forms. 
13B—17 . 
15—38 | . . 
17—62 | Overlap mode 
7—10 - bos 
3—7 Oversized buffers 
15—81 || ee 
4—5 |. 
15—64. 
D—28 
D—28 
D—28 
D—29 
D—29 
—-M 
eae 
E15 | 
15—3 
Th 
15—80 
4—4 
“15—79 
E—15 ‘ ‘ 
"+4 Padding 
3—2 |. Paper advance 
15—80. | 
vas! tape i management 
ASCII processing 
5—2 . character ‘and record types 
11—19 comparison of OS/3 with other 
13—24 systems | 
15—84 compatibility with IBM system/ 
360 DOS 
17—7° compatibility with 0S/4 
13—24 - compatibility with 9200/9300 
13B—19. considerations 
‘defining files (DTFPT macro) 
description 
processing files 
program connector board 
11—32 See also paper tape files. 


11—34 





index. 1.7.~ - 


Reference 


10.1 


114.12: 


Table 7—2 

See forms 

overflow.” 
Bao 


17515° 


Page 


10—2 


“li—17 


7—8 


17—33 


E—16 


1-10 


17—4 


17—73 


“17-74 


17—73 
1/—74 
17/—1 
17—24 
17-1 
17—15 
1/—2 
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Term Reference Page j-Term =~ ~ Reference Page 


. Paper tape. files. Parity check 


; ae - oe output functions, ISAM - 114.16  11—19 
| aa ie | ate 2 verification of output, oe ee 
buffers and work areas 17.5.1.4 17-30] | noningexed ash . wees a 
closing (CLOSE macro) 17.4.2 17—18 as wes ne 
defining (DTFPT macro) 175 p24 | Ta TO Soe meas 
description 1.3.7 1—9 ae tape 1759 7- 65 
end-of-record stop character, ate ; . Ale ee ees - 
output 1756 17-60} sequential disk files — -— - 15.65 .. 15—26 
error processing 17.5.9 17—65 - : | 
initializing (OPEN macro) i741 7—17 porntioh control appendage - See DPCA. macro. 
input, end-of-tape routine 17.5.4 17—49 a OI. Ae 
input — fixed, unblocked records Fig. 17—7 17—13:)" Fattitons =: ee 
input — shifted, fixed, unblocked  [-. s penne 
records Fig 17—9 17—15 os 


input — shifted, undefined records Fig. 17-8 17-14 | Peripheral devices 


input — undefined and fixed, : ante ae SH 
ea ae i ae - functional characteristics Appendix A 
leader and trailer Fig. 17-1 17—3 | 4, ia as 
letter/figure shifting and j FIOGS ule eae 
translation, input . 17.5.3 17—39 | on; . Ba 
letter/figure shifting and oN macro | 19.7.18 15- 108 
translation, output 17.5.5 17—50 | 5... oe aaa 7 
; ree Pointers 
ok fixed mae noes current record, ISAM W47:) 1-13 
pe tas fig 7-5 17—11 current 1/0 area, IRAM 134.11 13-21 
oversized buffers 17.5.1.5 17/—33 5 * 4 7 oer, 
srobessine 174 1715 POINTS macro « 15.7.6  «15—72 
processing mode specification 17.5.2 17—36 prime -data blocks 101 102 
punching logical record . . o 402. «1903 
(PUT macro) 17.4.4 17—22 aad ee ai ; 
oe Bae tod 743 20 | Print line, truncation ee ., A982, , PHO 
record format specification 17.5.1.2 17—29 pnp auanion ate Tak an [ae * 
record formats 1733 17—10 (PRTOV macro) TAA 724 
record size specification 17.5.1.6 17—35 ee or 
save area 17.5.8 17-63, 
type specification 17.5.1.1 17—28 |: 
Paper tape leader ee 17.2.2 - 17—3 
- . a / f Fig. 171 17-3 
. Paper tape loop, 0768 printer 6.4.4.4 6—10 | 
Paper tape records fo © 
fixed, unblocked ‘See fixed, 
fen * unblocked’ records. ee, 
formats 17.3.3 17—10] se a 
undefined ae oo See. undefined Pe 
: records. 
See also paper tape files. 
Paper tape subsystem characteristics -. Table A—6 A—11 
Paper tape trailer 17.2.3 17—3 


Fig 1/—1 17—3 


Oe 
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Term — 


Printer files 
description 
organization 
- printer forms 
record formats 
SAM a 


| tabular data. 
text ' 


Printer forms =e 
control (CNTRL macro) 
: description. 
sample printout 
special n 


Printer subsystems 
‘Characteristics 

files 

0768 

0770 

0773 

0776 

0778 


Program connector board 
description 
wiring for. tape punch 
“wiring for tape reader 


Program ming 


Programs, sample 


Punch 
card 
sdgpe. “RS 


Punched card files 
combined . 
description 
file organization 
input 
output 
record format 
SAM 


Structure - 
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Reference Page Term 
| re PUT macro 
1.3.4 1—7 diskette 
6.2 °. ~ 6—2 ISAM 

- 6.2.3 - 6-4 magnetic tape 
6.3 ~ 6—5 nonindexed disk 
See SAM files, overlap mode 
printer. paper tape 
6.2.2 - 6—4 printer 
6:21... 6—3 punched card 
74.3 7—21 
6.2.3 6—4 
Fig. 6—3 6—4 
6.4.4.3» 6—10 
Table A—3. A—4 
See printer files. 
6.1.3 6—2 
6.1.2 © 6+2 
6.1.1 6—2 

- 6.14 6—2 — 
615 ° 62 
ites: ap  §o R 
Z244:.- + 17-2 


17212 ~ 17-2 | Random disk files 
Get; ~~ creating by sequential load 
L4- 0). 1—9 


waiting on pomplenon of 1/0 
~ See sample — : Raion olitait . 
programs. : : 
Random processing 
om ae WRT eae ISAM files: 
See card punch. relative disk address 


See tape punch. : 
Random retrieval 
direct access files 


293 2-3 | ~ _IRAM files 


1.3.2 hoy records by relative disk address 
22 Dut rewriting blocks 
2.2.1 yay See also record retrieval. 
72.2.2 23 

Fig 2—2 2—2 READ, ID macro 
See SAM files, ; ISAM 
punched card. - nonindexed disk 
Fig. 2—1° 2—2 


READ, KEY macro 
ISAM 
nonindexed disk 


| Read lock 


Index:19 °~. 


Reference 


9.4.3 
11.5.5.3 
9.4.3 


VWAA 
74.2 
3.4.3 


15711): 


-15:7.16 


156.79 = 


Page 


9—10 
11—46 
9—50 


15-75 
958 
aye. 


7—18 
3—17 


15—86 


~ 15-105 


See WRITE ‘macro. 


15.6:24 © 


15.7.14 0) 


1323 >. 
15.7.14.1 
19.7.11.5 


11.5.4.1 
15.6:18 


15.7.14.1 


11.5.4 | 
15.6.19 © 
15.7.14.2 


16.1.4 


11-35 
—15—46 


15—97 
~ :13—11 


15—99 
15—93 


1 1—36 
15—40 
15—99 


11—36 
15—40 


~ 15—101 


16—4 
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Term ; 


READ macro 


Record deletion 
_. direct IRAM files 
-indexed IRAM files 
_ ISAM files 
- » sequential IRAM files 


Record descriptor word (RDW) 
Record format specification (RECFORM) 
ISAM 
magnetic tape 
nonindexed disk 
paper tape 
printer 


punched card 


Record formats 
card punch records 


diskette 


end-of-data job control statement 
fixed-length fs 


fixed-length unblocked, 


input and combined card ‘files . 


- ‘1/0 area contents, nonindexed - 
disk files 
~ASAM 
magnetic tape 


nonindexed disk files 
paper tape 
printer 


. Start-of-data job control statement 
variable-length 

Record interlace factor 

Record keys 

Record printer, current 

Record processing, diskette SAM 

files 
- combined 


-. input 
“output 


Reference Page 


157.14 
13.125 13-8 
1326:.-.. 13—14 
123 11-4 
13.1.15,. ..13—5 
143.2 14-8 
157.94 15—80 
ee ee a Ges 
9241 9-17 


9.6.20 15—40 


Table 15—6 15—41. 


17.5.1.2 17—29 
7.3 7—12 
3.3 3—9 
2.3.3 2—4 
Fig. 2—3 2—4 
4,3 4—4 
Fig 4—2 4—5 
2.3.2 2—3 
See fixed-length 
records. 

Fig, 2—2  2—2 


Fig. 15—1 15—24| 


10.2.1 10-5 
8.2.5 g—14 | 
Fig. 8—11. 8—14 | 
143-0 14-6 


6.3 6—5 
Fig. 6—4 6—6" 
2.3.1 2-3 


See variable-length 


‘records. 


1568 15-30] 


See keys. 


1A W113 


523 Bed | 


9.2.1 9—1 
9.2.2 9—2 
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Term — 


A5—97 |} Record retrieval 


adding records, IRAM 

direct access files (READ macro) 
direct IRAM files 

indexed IRAM files 


initializing (SETL macro) 
READ, 1D macro 


READ, KEY macro 


search argument 

- sequential IRAM files 
sequentially: processed disk files 
specifying type, ISAM 
terminating (ESETL macro) 
with update 

~See-also:GET macro. 


Record size, invalid - 


Record size specification 
(RECSIZE and RCSZ) 


magnetic ‘tape 
~. nonsequential disk 
. paper tape 
printer 
punched card: 


Record transfer, ensuring completion 
(WAITF macro) 


Record types, paper tape 
3173.30 =17—10] oe ae oy 
‘Recording density,- specifying 


: Records 


chaining, ISAM file 
deleting | 
“direct IRAM ‘files 
fixed-length : 
RAM 

logical 

paper tape 


retrieving 


Reference Page 


13.24. 13-12 


15.7:14. .. 15—97 
13.124 13-7 
13.2.3 +» 13—11 
13.2.5 13—13 
13.4.16 13—22 
11.5.5.1 © 11—41 
SEE READ, ID 
macro. 

See READ, KEY 
macro. 

11.4.9 11—14 
13.1.1.4 13—3 
15.7.12 ‘15—94 
11.415 11—18 
11.5.5.4  11—48 
13.2.5: 4 


“13-13 


17.5.9 © .17—65 


13.418 13-23 : 
W413. UF | 
9242 9-18 be 

156.21  15—42 

ec ee ee 
73 7-12 
3300 ce BEng 
11533 11-35 
173 17—4 
9332 9-34 


10.2.2 ... 10—10 
Fig 10—5 10—10 
See record 

deletion. 

See direct ©: 

IRAM files. - 

See fixed-length 
records. 

Fig. 12—1 12—4 
Fig. 12—2 12—5 
See logical 

records. 

See paper 

tape records. a 
See record 
retrieval. 
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Term | 


Records (cont) 
sequential disk files, 

output 
sequential |RAM files 


skipping 
updating 


variable-length 


Reel organization 
EBCDIC nonstandard volumes 


EBCDIC standard volumes 


EBCDIC unlabeled volumes 
Register save area 


Register specification 
ISAM 
magnetic ‘tape 
nonindexed disk 
printer 
punched card 


| Registers 
save area 
specifying for residual space 


- Relative block address 

accessing current 

positioning a file or 
partition 


Relative disk address 
Creating and updating blocks 
IRAM 
nonindexed disk 


random processing 

random retrieval 

returned after READ or 
WRITE macro 


Relative MIRAM files 
creating: 
deleting records. 
extending 
processing 
reorganizing 


retrieving and updating records 


Reference 


15.7.9.4 


* Page 


15—80 


See sequential 


IRAM files. 
See RELSE 


‘macro. 


See: updating 


_ records. 


See variable-length 


records. 


Fig. 8—4 
Fig. 8—5 


Fig. 8—1 


_ Fig. 8—3> 
Fig. 86: 


11.47 


iene: Ve 


15.6.11 
730° 
o0.e8 


8—6 
8—7 
8—3 
8—4 ° 
8—5 
8—8 


~~ See save area. 


11—13 
9-13 
15—34 
7—9 
3—6 


See save areas. 


15.6.32 


5.7.17 


157.18. 


19.7.11.4 
13.4.19 
15.6.7. 
15.6.22 
15.6.24 - 
15.7.14.1 


Table 15—5 
13B:2.7 


13B.2.10 
13B.2.8 


13B.2 
13B.2.11 


13B.2.9 


“15—54 


15—106 


15—108 


15—90 | 
13—23 © 


15—28 
15—42 
15—46 
15—99 


15—29 


13B—4 
13B—5 
13B—4 
13B—1 
13B—5 


13B—4 | — 


Term 


RELSE macro 
magnetic tape 
nonindexed disk 


RENAME macro 
Residual space, variable records 
Resource control 
Rewinding 
at close 
at open 


options 


Rewriting randomly retrieved 
blocks to disk 


_ SAM files, disk 


SAM files, diskette 

closing (CLOSE macro) 

defining (DTFCD macro) 

input record processing | 

opening (OPEN macro) 

output record processing 

retrieve next logical record 
(GET macro) 

writing (PUT macro) 


Reference Page 


947 9-58 
(157.13 1596 


16.2 16—6 
15.6.32 15—54 


‘See system 
resource control. 


9.2.5.4 9—23 
925.3 9—23 


OZ 5:2 9—22 


157.115 15-93 


152  15—3 


5.4.4 5—12 
5355 
621° Sel 
541 5-7 
522 5-2 
54.2. 5-8 
5.4.3 5—10 
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am files, magnetic tape 


ASCII. processing 

block numbers 

checkpoint dumps, bypassing 
closing (CLOSE macro) 
defining (DTFMT macro) 


delivering next logical record 
(PUT macro) 

description 

eliminating tape mark 

end-of-data processing, input 
file 

end-of-volume procedures, forcing 
(FEOV macro) 

error messages 

error processing 

extending 

file processing mode, changing 
(SETF macro) 

general rewind options 

imperative macros 


index register 

initiating processing (OPEN macro) 
input file direction 

1/0 buffers 


job control statements 


label processing 
multivolume 


optional, specifying 

parity errors 

processing in a work area 
reading next record (GET macro) 
record format 


record size 
register save area 
rewinding 


secondary 1/0 buffer ~ 

short output blocks, writing 
(TRUNC macro) 

skipping to next input block 
(RELSE. macro) 

tape movement 

tape unit functions, controlling 
(CNTRL macro) 

type of processing 

type of tape labels 

user tape labels, processing — 
(LBRET macro) 

variable records, blocking 


SPERRY UNIVAC OS/3 > 


Reference Page Term 


SAM files, printer 


9.2.7 9—2/ closing (CLOSE macro) 
9.2.3.5 9—15 control printer forms 
9.2.8.2 9—29 - (CNTRL macro) 
9.4.2... -9—48 defining (DTFPR macro) 
9.2 9-1 device-independent control 
9.2.1 9—2 character codes 
--error and exception handling 
9.4.3 9—50 functional description 
9.1 9—1 ‘opening (OPEN macro) 
9.2.6.2 9—24 output a record (PUT macro) 
print overflow action 
9225 9-12 (PRTOV macro) 
_ sample program 
9.4.8 9—59 nical operating sequence 
93,7 9—43 
9.2.2.4 9—12 | SAM files, punched card 
9.3.6 9—4]1 closing (CLOSE macro) 
controlling stacker selection 
9.4.5 9—54 (CNTRL macro) 
9.2.5.2 9—22 defining (DTFCD macro) 
9.4 9—43 description 
Table 9—4 9—44 error and exception handling 
9.2.3.2 9—13 input 
9.4.1 9—46 opening (OPEN macro) 
9.2.5.1 9—22 output 
9.2.2.1 9—10 output a record (PUT macro) 
9.2.2.2 9—10 | retrieving next logical record 
See job control (GET macro) 
statements. i sample programs 
9.2.6 9—23 et eS 
9.2.10 9—30 | Sample programs 
9.3.5 9—40 printer 
9.2.8.1 9—28 punched card 
9.2.3.4 9—14 : 
9.2.3.3 9—14 | Save area specification 
9.4.4 9—52 ISAM 
9.2.4 9—17 magnetic tape 
9.2.4.1 9—17 nonindexed disk 
9.2.4.2 9—18 |. paper tape 
9.2.2.6 9—13 . printer’ 
9.2.5.3 9—23 punched. card 
9.2.5.4 9—23 
9.2.3.1 9—13 | Scan tables, letter/figure 
9.4.6 9—56 | SCR job control statement 
(94.7 9—58 | Scratch volume 
9.2.5 ~  9—21 
: SCRTCH macro 
9410 9-62 rae 
9.2.2.3 9—11 | Search 
9.2.6.1 9—23 key, address of argument 
; 4-level piu index 
9.4.9 9—60 


9.2.4.3 9—19 Seartli -by-key junction 


Index 22 


Reference 


745 


7.43 
73 


Table 7—1 


7.6 
Tid 


7.6 
36 


114.14 
9.2.2.6 
15.6.23 
1158 
a13-93 
17.55 
16.1.3 
9.3.3.3 


16.3." >. 


19.6.12° © 


Fig. 12—6 


» Page 


3—24 


3—19 


1—10 


3425 


3—1 
3—14 


3—17 
3—15 
3—25 


7—28 
3==25 
11—18 


15—45 


15—35 
12—8 


10—1 


© 


«ens, 
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Term 


Search-on-key function 
Sectors, disk 

Sequence check 
Sequential access method 


Sequential-by-key retrieval sequence 


Sequential disk files 
creating 
extending existing DIFSD 
optional 
output of blocked records 
output of DIFNI with keys 
parity errors 
reading, with and without 

record interlace 

reserving space 
retrieving records (SET macro) 
update processing mode 
updating and extending 
See also disk files. 


Sequential IRAM files 
adding records 
creating 
deleting records 
extending 
nonindexed 
processing 
reorganizing 
retrieving and updating records 


Sequential ISAM files 
Sequential load 


Sequential MIRAM files 
adding records 
creating 
deleting records 
extending : 
processing 
reorganizing 
retrieving and updating records 


Sequential processing, work area 


Set file load 


SETF macro 


Reference 


11.4.9 
12.2.2 
13.4.20 
See SAM. 


13.2.3 
13B.2.4 


19.7.9:1 
thew ee aS 
15.6.16 
15.7.9.4 
13.7.9:0 
15.6.5 


Fig. 15—2 
16.1.2 
15.7.12 
15.6.31 
15.7.9.2 


13.1.1.3 
ie Ba 
13. L135 
13...12 


a 


13.1.1 
13-b.15 
13.1.1.4 


ae ae pe 


15.7.11.1 


13B.2.3 
13B.2.1 
13B.2.5 
13B.2.2 
13B.2 

13B.2.6 
13B.2.4 


Page 


11—14 
12—3 


13—23 


13—11 
13B—3 


15—76 
15—79 
15—38 
15—80 
15—80 
15—26 


15—31 
16—2 
15—94 


15—54 |} 


15—78 


13—3 
13—2 
13—5 
13—3 
13—1 
13—2 
13—5 
13—3 


11—40 


15—86 


13B—3 
13B—2 
13B—3 
13B—2 
13B—1 
13B—3 
13B—3 


See work area 


specifications. 


See SETFL 
macro. 


9.4.5 
15.7.8 


9—54 


15—74 


Term 


SETFL macro 
SETL macro 
SETP macro 
SETS macro 
Shared data management modules 
Shift characters 
Shift codes 
paper tape record 
translation for input files 
translation for output files 
Shifted, fixed, unblocked records 
Shifted, undefined records 
Short variable blocks, output 
magnetic tape 
nonindexed disk 


Skip codes, device 


Skipping records 


Software, related OS/3 


Space requirements 


Special forms 
Stacker selection 


Standard labels, disk 
header 


optional user 


system, nonindexed files 
trailer 


Standard labels, tape 
ASCII 


system 


Reference Page 


11.5.2.1 11—27 


1155.1 © 11—42 
15.7.4 15—68 


15.7.5 15—70 


15.7 1—12 
173.2 17—6 
Fig. 17—4 17—9 


17.9.3.2 1/—46 
1735) 17—50 


Fig. 17-9 17—15 


Fig. 17-8 17—14 
9.4.6 9—D56 
15.710 15—82 
Table 7—4 7—22 


See RELSE 
macro. 


17 1—15 


See disk space 
requirements, 


estimating. 

6.4.4.3 6—10 
3.4.4 3—19 
D.4.1 D—28 
Fig. D—14  D—28 
14.2.4 14—5 
15.7.3 15—64 
D.4 D—28 
14.2.3 14—4 
D.4.2 D—29 
Fig. D—15 D—29 
See ASCII 

standard 

magnetic 

tape labels. 

See system 
standard 


tape labels. 
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Term 


Standard modes, data conversion 


Standard volume organization 


Start-of-data (/$) job control 
statement 


Stop character 
description 


specifying end-of-record, output 
files 


Stub card read feature 


Subfiles 
DTFNI partitions 
processing in partition 
support in partition 


Supervisor 
System access technique 


System code field 
description 
file header labels 


System error messages 
data management 


description 
disk space management 


System macro library 


System resource control 

device allocation and file 
assignment 

disk space management and 
the VTOC 

dynamic deallocation of disk 
file (SCRTCH) 

file lock feature 


renaming disk file (RENAME) 

retrieving VIOC information 
(OBTAIN) 

sample device assignment set 

use of job control statements 


SPERRY UNIVAC OS/3_ 
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Reference Page 
C.4 C—10 
See volume 
organization. 

2.3.1 2—3 
17212 17-3 
17.3.1 17—6 
17.5.6 17—60 
3.3 3—10 
14.2.2 14—3 
15.7.5 15—70 
15.6.27 15—50 
(1.7.3 1—17 
1.7.3 1—17 
E.3.2.4 E—16 
E.2.2.1 E—4 
E.2.2.2 E—/ 
B.3.1 B—2 
Table B—1 B—3 
B.3 B—2 
B.3.2 B—10 
Table B—2 B—11 
7.2 7—1 
16.1 16—1 
16.4 16—11 
16.3 16—8 
16.1.4 16—2 
Table 16—1 16—4a 
16.2 16—6 
16.4.1 16—12 
16.1.2 16—2 
16.1.1 16—1 


Term 


System standard tape labels 
description 
file header label group 
file trailer label group 
user header and trailer 
volume label group 


Tabular data 
printer files 
sample printout 


Tape files 
magnetic tape 


paper tape 
Tape labels 


Tape mark, eliminating 


Tape punch, wiring program 
connector 


Tape reader, wiring program 
connector 


Tape volume 1 label 
Text 
output example 
printer files 
Timer services 
Tracks 
extending key search 
new; selecting and initializing 


Trailer, paper tape 


Trailer labels 


Index 24 
Update C 


Reference 


E.1 

E.2.2 
E.2.3 
E.2.4 
E.2.1 


6.2.2 
_ Fig. 6—2 


See magnetic 


tape files. 
See paper 
tape files. 


See magnetic 


tape labels. 


9.2.6.2 
17.2.1.1 


17.2.1.2 
See VOL1 
label, tape. 
Fig. 6—1 
6.2.1 

1.7.3 
15.6.26 
15.7.11.2 
17.2.3 


See user 
trailer labels. 


Page 


E—1 
E—4 
E—9 
E—14 
E—2 


6—4 


6—4 


9—24 


17—2 


17—2 


15—50 
15—88 


1/—3 
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Term 
_ Transient scheduling 
“Translate mode. 


“Translation, paper tape files 


input files, character mode 
input files without shifted 
_ codes ~ 
output files 
-unshifted output files, either 
mode — 


“Translation table address 


_ TRUNC macro 


magnetic tape 
— monindexed disk 


Truncation, print line 


.. Type of file, specifying 


4 


U 


Unblocked records, paper tape 


Undefined records, paper tape 


followed -by interrecord gaps 


formats — 

input, length relationships to 

\ .BLKSIZE, and content of RECSIZE 
_register. . 
output, standard mode 

record. length and BLKSIZE 

relationship 
shifted, user work area 


SPERRY UNIVAC 0S73 -- 


Reference 


LS 


C.4 


17.5.3 


175.32. 
1755 


17.5.5.1 


33 


946 | 
157.10 


7.5.2 


See fixed, 
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9—56 
15—82 


/—28 


See ‘file type | 
. specification. 


unblocked records. 


Fig. 17—5 
Fig. 17—6 
173.345. 


Fig. 17—4 
Fig. 17—3 


Fig. 1/—2 
Fig. 17—8 


1/—11 
1/—12 
17—10 


1/—9 
17/—8 


76" 
17—14 


. Update processing mode 





Term . 


Unique (parity) error 


- UNISERVO subsystems, characteristics 


Unlabeled volume organization, 
EBCDIC 


. Unrecoverable. error 
‘| Unshifted files... . 


_Update functions, forestalling 


Updating disk files 


Updating input blocks 
by key 
by relative disk address 


Updating records 
direct IRAM files 
indexed IRAM files 
ISAM, UPDT macro 
ISAM file, random processing 
sequential. IRAM files 
UPDT keyword, DTFIR macro 


UPDT macro. 

User header labels 
eliminating tape mark 
nonstandard, tape 
standard, disk 


standard, tape 


~ User interface: 


User labels, disk 
creating 
processing 
receiving: or updating 


‘See also optional user labels, disk °° 


User labels, tape 


User trailer labels 


nonindexed disk 
nonstandard, tape 
-standard, disk 


standard, tape 


Index :25 . 


Reference. 


17.5.9 


~. Table. A—5 © 


823° 
1759 | 
175.51 


11.4.16 


i 15 6 Al 


asst 9D 


15.7.14.2 » 
19.7.11.4, . 


13.124 
13.2.3 
ve T1643" | 
11.5.4.2 ° 
2 ABLIA 
~13.4.22> - 


11.5.4.3 


9.2.6.2 


SRA eee es 


14.2.4.1 - 
D.4.1 
8.2505 
rE2.4°: 


cps EB: gear 


ce, 157.31 
15.7.3 .--; 
15.7.3.2 


i 


pEQA sn : 


Page 


17/—67 


A—10 


38 


17—68 


17—58 


11—19 


15—54 


I5—78 


15—101 
I5—90 


13—/7 
13—11 


~ 11—40 


11—38 
13—3 
13—24 


11—40 


. 15—66 


15—64 
15—67 


15—51 


14—6 
D—29 


E—14 
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Term 


~ Validity check errors 


Variable-length records 
. ASCII 

blocking in 1/0 area 
diskette 

ISAM 

keyed, nonindexed disk files 
nonindexed disk files 


output of blocked records, 
sequential disk files 

output of short blocks 

specifying register for residual space 

See also record formats. 


Variable sector support 
IRAM files 
MIRAM files 
Version number, file 
© Vertical format buffer 
. definition 
interchangeability 
VFB statement specification 
See also. VFB statement. 


VFB job control statement 


VFB statement specification 
description 
example © 
forms overflow position 
home paper position 
paper tape loop 
special forms 


~ VOL job control statement 
description 


effects on OPEN transient 


Volume information group labels, disk 
description 


format 0 


format 4 
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Reference Page 


33. 3-4 
9273 9-28 |. 
9.2.43 9—19 
Aao aed. 
10.2.1 10—5 

Fig. 144 14 —12 
14.3.2 14—8 

Fig 1443 14—9 
157.94  15—80 


See TRUNC macro. 


15.632 ~15—54 
1352 13-27 
1386.2 13B—21 

9346 © 9-39 
Bi, 9 21 
6.4.3 69 
644° 6-9 
Table 6—1 6—11 
6A deo! 16-1 
GAA 69 
Table 6—1 6—11 
6445 ° 6—12 
6442 6-9 
6441 6~9 
6.44.4 .° 610 
64.4.3  6—10 
9.3.3 9—33 

6 1611 16—1 

“<-- Table 9—3 9—38 
Dl p41 
D2 ae 
D.2.5: D—11 
Fig. .D—6 D—Il 
Table D—5 D—11 
D.2.2 p—4 
Fig. D3. D—5 
Table D—2 D—6 


Term 
format 5 
format 6 
VOL1 


VTOC 
Volume label group, magnetic tape 


Volume organization 
disk 
diskette 
EBCDIC, magnetic tape 


Volume serial number 
checking 
inhibiting checking 
SCRICH macro 
volume label group, tape 


Volume table of contents (VTOC) 
ISAM files 
SCRICH macro 
disk space management 
retrieving information (OBTAIN) 
volume labels, disk 


file labels, disk 


Volumes 
definition 
file. processing, one volume online 
multifile 
scratch 
specification statement (VOL) 


VOL1 label, disk’ 
contents 
description 


VOL1 label, tape 
ASCII 


contents 
description 


93.4.2 


Index 265... 


Reference 


D.2.3 
Table D—3 
D24 | 
Fig. D—5 
Table D—4 
O21 
Fig. D—2 
‘Table D—1 
Fig. D—1 


E21 


D.2 


~ Fig. 4—1 
See EBCDIC volume 


organization. 


9.3.3.1 
16.3 
E21 


10.1 

16.3 

16.4 

16.4.1 

See volume 
information g 
labels. 


Page 


~ aESe 


D—8 
D—9 
p—9 
D—10 
D—10 
D—3 
D—3 
D—4 
D—2 


nee 


D—2 
4—2 


9—36 


9—34 
16—9 
E—2 


10—2 
16—8 
16—11 
16—12 


roup 


See file information 


group labels. 


1.3.1 
13.4.13 

See multifile 
9.3.3.3 

9.3.3 


Fig. D—1 
D:2 


“21 


Fig, D2 


Fig. E—7. 


~~ Table E+-7 


Table E—1 


ees 4 ee 


Fig. E=1. 


1—6 

13—21 
volumes. 
9—36 
9—33 


D—4 
D—2 
D—3 
D—3 


E—17 
E—18 
E—4 
E—2 
E—3 
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Term Reference Page Term Reference Page 
VSN See volume serial Work areas, paper tape 
number. record lengths Fig 17—4 17~—9 
shifted, fixed, unblocked records, 
VTOC See volume table input file Fig. 17—9 17—15 
of contents. shifted, undefined records, input file Fig. 17—8 17—14 
specifying 17.5.1.4 17—32 
WRITE, AFTER, EOF macro 15.7.11.3 15—89 
WRITE, AFTER macro 15.6.2 15—21 
15.7.11.1 15—86 
WRITE, ID macro 15.6.35 15—56 . 
15.7.11.4  15—90 
WRITE, KEY macro 
description 15.7.11.5  15—93 
ISAM 11.5.4.2 11—38 
nonindexed disk 15.6.36 15—5/7 
WAITF macro 
ISAM 11.5.3.3 11—35 | WRITE, NEWKEY macro 115.22  11—28 
nonindexed disk 15.7.16 15—105 11.5.3.1 11—32 
Work area specifications WRITE, RZERO macro 15.6.2 15—21 
IRAM 13.4.25 13—24 15.7.11.2  15—88 
ISAM 11.4.18 11—19 
magnetic tape 9.2.3.3 9—14 Write lock 16.1.4 16—3 
nonindexed disk 15.6.34 15—56 
paper tape 17.5.1.4 17—31 | WRITE macro 15.7.11 15—84 
printer 7.3 7—13 
‘punched card 3.3 3—11 Wrong length error 17.5.9 17—67 
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